Troubleshooting

Failed builds and Maestro runs show explanations only when their saved output contains matching evidence. Suggestions do not change signing credentials, clear caches, start retries or submit builds. A generic failure is not treated as a confirmed root cause. Updated managed test runners report actual attempts so a pass after retry remains visible; historical runs without that data do not claim a first-attempt pass.

Error 65: xcodebuild failure

This usually happens if your name in mach.config.json doesn't match the capitalized project name in Xcode. Mach's build system now auto-detects and patches this for you.

Prebuild: Unknown Option

Older versions of Expo CLI don't support --bundle-identifier. Mach handles this by temporarily patching app.json instead of passing flags.

Pod install fails on cloud build

Usually a cache issue. Re-run the build with a fresh cache. Mach caches CocoaPods per project — a new dependency may require a clean install.

Missing Android credentials: Signing Keystore

Check the package id and signing type for the selected profile. Dev-client builds use development signing credentials even when `distribution` is `internal`.

iOS build number already used

If App Store Connect rejects an IPA because the bundle version was already uploaded, seed the DB counter with `mach version seed --platform ios --value <latestBuildNumber>`, then enable iOS auto versioning with `ios.buildNumber: "auto"` or run `mach build --platform ios --profile production --auto-version`.

Build job passed but Dashboard stayed building

Update the Mach CLI on the runner. Current builds retry artifact upload/final status updates and mark the build failed if the Dashboard cannot be finalized, so the row does not stay stuck.

Session expired / 401 errors

Run mach me to check the selected account and how it was selected. Mach refreshes that account’s token automatically. If its session has fully expired, run mach login for the same account. CLI 2.12.0 and later save local sessions in ~/.mach/accounts.json and migrate the previous ~/.mach/credentials.json session on the first account update or refresh. MACH_TOKEN takes priority over saved logins; unset it separately when you want to use an interactive account.

Wrong account or a removed project login

Run mach accounts, then mach switch to choose a saved project member. Project preferences stay in place after logout so a command cannot silently use another account. Use mach switch --clear-project to remove the preference and use the default. A switch does not grant project access; the selected account must already be a project member.

AWS STS token errors

STS tokens are temporary and fetched from the Dashboard. If you see permission errors, ensure your Dashboard account has the correct AWS role configured.

[Decryption Failed] in Secrets

This happens if your `MACH_ENCRYPTION_KEY` has changed. Secrets are encrypted with this master key. If it changes, the old secrets are unreadable. To fix, delete the broken secrets and re-add them using the current key. Mach treats this as a configuration issue rather than silently shipping `[Decryption Failed]` inside the app.

npm 403 Forbidden (Deployment)

Publishing to npm requires 2FA or a Granular Access Token with "Bypass 2FA" enabled. Ensure you are logged into npm and have your authenticator app ready for the OTP prompt during deployment.

Profile not found

Check that your `mach.config.json` has the profile defined under the `build` key. Use `mach config --profile [name]` to debug the resolved configuration.

Circular inheritance detected

Profile A extends B, which extends A. Mach detects this and throws an error. Fix by removing the circular `extends` reference.

Unknown option --profile

Update to the latest Mach CLI build. `mach submit --latest --platform android --profile production` is supported by current CLI versions and filters the selected build by profile.

No Google Play service credential found for package

Android service credentials must be uploaded against the exact package id. Run `mach credentials:service --platform android --package-name com.example.app --file path/to/service-account.json`, or omit `--package-name` to select from package ids saved in the Dashboard.

Android versionCode already used

Seed the DB counter with mach version seed --platform android --value <latestVersionCode>, then run with android.versionCode: "auto" or pass --auto-version. Mach will assign the next value from its own counter.

fastlane not found on Linux CI

Android submit no longer needs Fastlane. iOS submit is queued through Mach and must run on the configured macOS runner because Fastlane pilot and Xcode tooling are macOS-only.