migrate.sh reports "No .xcodeproj or .xcworkspace found".

Run the script from the project root where your .xcodeproj or .xcworkspace file is stored.

migrate.sh picks the wrong build entrypoint.

Pass --scheme YourScheme and --verify-build to force a specific build path.

The project is not a Git repository.

iOS migrations require a Git baseline. Run prompt 00pre-bootstrap.md again. The agent asks for consent before running ensure-git-baseline.sh --consented, which initializes Git, excludes toolkit artifacts, and creates the pre-migration baseline commit.

Git baseline commit fails because user.name or user.email is missing.

Configure Git identity, then run prompt 00pre-bootstrap.md again. To set the user name and email for this app only, use git config user.name "Your Name" and git config user.email "you@example.com". To set these values globally, use git config --global user.name "Your Name" and git config --global user.email "you@example.com". No remote or GitHub account is required.

Your agent invents APIs that do not exist.

Instruct the agent to "Only use APIs from the steering files and the API catalog. Do not invent APIs."

The build fails after migration.

Clean and rebuild with xcodebuild clean build. Check steering/95-troubleshooting.md for additional guidance.

Secure APIs fail or return unauthorized before unlock.

Secure APIs were called before onAuthorized() or the authorized event. Tell your agent to run prompt 03-add-dynamics-auth.md again and the 03b-authorization-deferral-audit.md deferral audit.

GDInitializationError occurs at runtime.

Check Keychain Sharing (com.good.gd.data), GDApplicationID and GDApplicationVersion in Info.plist, and that GDiOS.sharedInstance().authorize(...) runs from AppDelegate.application(_:didFinishLaunchingWithOptions:). Run prompts 01–03 again as needed. See steering/95-troubleshooting.md.

Validation fails on a specific phase.

Tell your agent which phase failed and ask it to run the owning prompt again (for example, "Phase 5 failed validation — re-run prompt 05-filesystem-migrate-to-gdfilemanager.md"), then run validate.sh --check-prompt <id> and record-prompt-execution.sh.

The recorder refuses to mark a prompt complete.

Prerequisites in check-prompt-map.json are not satisfied, or scoped validation did not pass. Fix the owning prompt or domain. Do not edit executedPrompts[] manually.

Your agent guesses values for GDApplicationID or GDApplicationVersion.

Stop the migration process. You must define these values. For more information, see BlackBerry Dynamics SDK migration toolkit: Prerequisites and considerations.

migration-report.json is missing fields or the viewer rejects the schema.

Ensure prompt 10 wrote schema v2.1.0. Run prompt 10-generate-migration-report.md again.

The report viewer shows nothing.

Validate the JSON: python3 -m json.tool dynamics-migration-tool/output/migration-report.json. If you opened the HTML from a different location, use the file picker to select the JSON manually.

validate.sh or the recorder exits with code 3 (ESCALATION REQUIRED).

The retry budget may be exhausted from repeated failures. Review dynamics-migration-tool/output/migration-loop-state.json, fix the owner prompt or domain, and run targeted checks again before another full attempt.

CocoaPods integration fails.

Ensure pod install completes cleanly first. Use the .xcworkspace entrypoint. See CocoaPods guidance in steering/10-xcode-integration.md.

Swift Package Manager package resolution fails.

Try File > Packages > Reset Package Caches in Xcode. See SPM guidance in steering/10-xcode-integration.md.