migrate.sh reports "not an Android project".

Run the script from the project root where app/build.gradle or your application module build file is stored.

Prompt 00pre-bootstrap.md stops the process with a network failure.

Network access to the BlackBerry Maven repository is required. Whitelist *.blackberry.com for your agent or network proxy, then run 00pre-bootstrap.md again.

The project does not use a Git repository.

The migration process can continue without Git. Git is optional, but is recommended for rollback and audit: git init && git add -A && git commit -m "pre-migration baseline".

Prompt 00pre-bootstrap.md stops the process when it checks your agent permissions.

Grant your AI coding agent file read, file write, shell execution, and full network access permissions, then run 00pre-bootstrap.md again.

Prompt 00pre-bootstrap.md reports issues with the JDK, Gradle, or minSdk.

Review output/.bootstrap-probe.json for the specific issues reported by the toolkit. Verify that you meet the toolkit prerequisites.

Your agent invents APIs that do not exist.

Instruct the agent: "Use only APIs from the steering files. Do not invent APIs."

The build fails after migration.

Run ./gradlew build --stacktrace and review steering/95-troubleshooting.md to identify and resolve the build issues.

GDNotAuthorizedError occurs at runtime.

Secure APIs were called before onAuthorized(). Ask the agent to run prompt 03b-authorization-deferral-audit.md again.

GDInitializationError occurs at runtime.

An activity is missing activityInit(). Ask the agent to run prompt 03-add-dynamics-auth.md again.

An IllegalStateException: Can not perform this action after onSaveInstanceState error occurs after BlackBerry Dynamics activation or unlock.

A runOnAuthorized(...) callback committed fragment transactions after an activity state was saved. Run prompt 03-add-dynamics-auth.md again and apply lifecycle-safe authorization UI initialization before fragment commits (isStateSaved guard + deferred retry in onPostResume).

Validation fails on a specific phase.

Check output/.last-check.json and the recorder stderr. Tell the agent which checks failed and run the relevant prompt(s) again. The recorder will automatically run scoped checks again on the next record call.

validate.sh flags Room, OkHttp, or direct File / createTempFile.

Run the relevant migration prompt (04, 05, or 06) again, or add the domain to deferredDomains[] in bootstrap.json with developerSignedOff: true if you intentionally accept the gap.

Prompt 10 reports EXECUTION PLAN GATE FAILED.

An applicable domain does not have a completed prompt or a signed-off deferral. Run the listed prompts again or add deferredDomains[], then run prompt 10-generate-migration-report.md again.

Your agent guesses values for GDApplicationID or GDApplicationVersion.

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

settings.json does not match bootstrap.json.

Run prompt 02-create-settings-json.md again to overwrite settings.json using the values from bootstrap.json.

migration-report.json is missing fields.

Run prompt 10-generate-migration-report.md again with schema v2.1.0 steering.

The report viewer does not display any information.

Run the following to validate the JSON: python3 -m json.tool dynamics-migration-tool/output/migration-report.json

executedPrompts[] includes duplicate entries.

Run the offending prompt again. record-prompt-execution.sh is idempotent and should replace the prior entry.