Troubleshooting

Locked build database

Stop active Xcode builds and rerun serially with a new, target-specific -derivedDataPath. Do not share DerivedData between concurrent builds. See Clean Build Procedure.

Diagnostic result is Not tested

This is expected until an operator runs the guide on physical hardware. Simulation validates state transitions but cannot mark the hardware check Passed.

Simulated iPad Warning Center — Figure 1. iPad — Plain-language warnings, technical details, status, and suggested actions. Simulated research data.

Workspace or project is missing

Install XcodeGen, run xcodegen generate at the repository root, and reopen OrganicVision.xcworkspace.

“Signing requires a development team”

Select the affected app target, open Signing & Capabilities, enable automatic signing, and choose a team. Repeat for all three app targets.

Bundle identifier is unavailable

Change each PRODUCT_BUNDLE_IDENTIFIER in project.yml to a unique reverse-DNS value, regenerate, and reopen the workspace.

Device is unavailable or untrusted

Unlock and reconnect the device, accept trust prompts on both Mac and device, enable Developer Mode, and check Window → Devices and Simulators. Trust the developer identity under Settings → General → VPN & Device Management if iOS requests it.

Package resolution or stale build errors

Use File → Packages → Reset Package Caches, then Product → Clean Build Folder. If the manifest itself fails, run swift package describe to expose the package error directly.

Camera produces no frames

Confirm Camera access under Settings → Privacy & Security → Camera and use the in-app Settings shortcut after denial. The simulator intentionally displays a generated preview rather than camera frames. On device, stop other camera applications, foreground OrganicVision, and retry after an interruption.

Recording will not start

Provide a session name and confirm that at least 1 GB is available. Only one recording can be active. If a prior launch was interrupted, OrganicVision marks its package incomplete during startup so it remains reviewable.

Location or motion is missing

Location may be denied, restricted, inaccurate indoors, or slow to produce a first fix. Motion depends on device availability. Missing values are not fabricated and the manifest records availability. The iOS simulator emits deterministic values labeled as simulated.

Export cannot be shared

Tap Prepare Export first, then use Share Raw Session Package. The .organicvision export is a directory package; choose a destination that accepts file packages. The app does not upload automatically.

Camera Node does not appear on iPad

Confirm both devices are on the same local Wi-Fi network, grant Local Network permission, and keep both apps foregrounded for initial pairing. Guest networks, client isolation, VPNs, captive portals, managed networks, and some routers block Bonjour. Check firewall rules on any macOS observer. The advertised type is _organicvision-v1._tcp.

Verification codes differ

Reject pairing. Restart discovery and compare a new code on both devices. Never approve a mismatched or expired code. If a known device changes identity, forget the prior pairing and deliberately pair again.

Connection repeatedly reconnects

Move devices closer to the access point, disable Wi-Fi client isolation, and confirm both remain on the same subnet. Recording continues locally on iPhone; do not stop it merely to restore the preview. Protocol-incompatible builds must be updated to the same OrganicVision version.

Remote recording is denied

Enable remote control on iPhone and approve its first-use warning locally. Pairing alone does not authorize start/stop. Remote control cannot grant permissions, delete sessions, or change security settings.

Dataset catalog and HTML documentation

Catalog unavailable or damaged: preserve catalog-v2.json and its .backup file before further changes. OrganicVision reports corruption rather than discarding records.
Package rejected: inspect the plain-language error. Remove symbolic links/executables, repair unsafe or missing relative paths at the source, and never bypass validation.
Integrity mismatch: keep the package quarantined and compare it with the source; do not regenerate integrity data merely to hide an unexplained mismatch.
Transfer interrupted: retain the staging folder and checkpoint so missing chunks can resume. Do not catalog partially assembled data.
HTML search does not work locally: some browsers block fetch from file://. Upload the complete folder to the LAMP host or serve it locally with python3 -m http.server from HTML Documentation.
HTML content is stale: run python3 Tools/generate_html_documentation.py from the repository root and upload the entire regenerated folder, including search-index.json.

Vision analysis

No boxes appear: enable analysis, lower the threshold, confirm a compatible model, and check whether thermal pressure paused work.
Boxes do not align: verify orientation, mirroring, source dimensions, and preview gravity; never rewrite stored normalized boxes as a display workaround.
Model rejected: confirm compiled Core ML compatibility, SHA-256, recognized-object output, OS requirement, and license metadata.
Resume rejected: the input hash changed. Preserve the earlier run and start a new one.
Run left in .processing: use interrupted-run recovery; do not rename it manually.
Scores seem implausible: inspect evidence explanations and unknown. Scores are experimental, not proof.

Annotation and training export

Workspace opens the dashboard: confirm the deterministic route includes -organicvision-annotation-mode.
Autosave or recovery fails: preserve the annotation project and recovery/edit-journal.jsonl; do not replace the source session or analysis integrity manifest.
Export validation fails: correct the listed geometry, category, ID, split, frame, or safe-name error. A failed export must not be finalized.
Privacy warning remains: metadata exclusion cannot remove faces, plates, homes, or private property from pixels. Perform a visual rights, privacy, bias, and licensing review.