Troubleshooting

Last updated 2026-10-07

Common symptoms and how to fix them. If your error isn't listed, or the fix doesn't help, ask Claude with the prompt below.

Ask Claude

Copy the prompt, open Claude, and fill in the <…> placeholders. The prompt gives Claude the framework's structure, so it can point to the exact config value instead of suggesting Fastfile edits.

Ask Claude

General troubleshooting prompt: works for any failed lane.

Open Claude

I use the Mobile Fastlane Framework: a configuration-driven fastlane setup with a generic Fastfile + fastlane/lib/*.rb (do not fork per project). Project settings live in fastlane/config/environments.yml, testing.yml, test_case_ids.yml and saved setups in fastlane/config/profiles/*.yml; secrets come from .env or CI secrets. Android builds with Gradle and distributes via the firebase_app_distribution plugin (optional Firebase App Testing agent); iOS builds with build_app and uploads with upload_to_testflight. fastlane 2.240.1, run with bundle exec.

My run failed. Details:
- Platform: <android | ios>
- Environment / profile: <e.g. staging, or profile development-apk>
- Command I ran: <e.g. bundle exec fastlane android distribute environment:staging>
- OS / CI: <Windows 11 local | macOS | GitHub Actions>
- What I expected: <…>

Error output (include the "Called from Fastfile at line …" block, the fastlane summary table and the first lines of the Ruby backtrace):
```
<paste the log here>
```

Relevant config (secrets removed):
```yaml
<paste the environment block from environments.yml and/or the profile file>
```

Please:
1. Explain the root cause in plain words.
2. Tell me exactly which value or setting to change (environments.yml, a profile, .env, Firebase console, App Store Connect, Teams…). Only suggest editing the Fastfile or lib/ if it is clearly a framework bug.
3. Give me the command to verify the fix, preferring `bundle exec fastlane <platform> doctor environment:<env>` or `bundle exec fastlane run_profile name:<profile> dry_run:true` before a full build.

Warning: remove secrets before pasting: FIREBASE_TOKEN, service-account JSON, .p8 keys, passwords and webhook URLs (anything containing sig=). Replace them with <redacted>. Group aliases, app IDs and lane output are fine to share.

Known issues

403 PERMISSION_DENIED → "App Testing Agent test execution failed: Invalid request"

Fix: The App Testing agent rejects service accounts. Use FIREBASE_TOKEN from firebase login:ci with the account that opted in; confirm the owner opted in and the Tool Results API is enabled.

Manual testers didn't receive the build

Fix: The group alias in FIREBASE_ANDROID_<ENV>_GROUPS must exactly match the alias in Firebase. With AI tests on, the framework distributes first.

Test Case <id> not found

Fix: The ID in test_case_ids.yml must match the console ID and belong to the same Firebase app.

AI test fails after login / sees a blank screen

Fix: FLAG_SECURE is enabled for that screen.

AI test quota exceeded

Fix: The limit is 200 tests/month; reduce devices or test cases.

R8: Missing class com.gemalto.jp2.JP2Decoder

Fix: Add -dontwarn com.gemalto.jp2.** to android/app/proguard-rules.pro (optional JPEG2000 decoder used by pdfbox-android).

Gradle task 'X' was not found

Fix: Fix gradle_task (exact task name, flavors included).

No APK artifact found

Fix: artifact.glob doesn't match the Gradle output folder.

Missing required configuration: …

Fix: The YAML value is empty or the ${ENV_VAR} isn't set.

Teams: "Property 'type' must be 'AdaptiveCard'"

Fix: The webhook needs an Adaptive Card payload; update to the latest notification_helper.rb.

Invoke-RestMethod: Uri … null or empty

Fix: PowerShell doesn't load .env; set $env:TEAMS_WEBHOOK_URL first.

iOS lanes require macOS with Xcode installed

Fix: Expected on Windows/Linux.

iOS workspace … does not exist

Fix: pod install failed; run cd ios && bundle exec pod install.

iOS scheme '…' was not found

Fix: Mark the scheme as Shared and commit xcshareddata.

TestFlight: bundle version already used

Fix: Set BUILD_NUMBER or keep auto_increment_build_number: true.

`fastlane setup` is interactive. In CI use: fastlane run_profile name:<profile>

Fix: setup and init_project need a person to answer. In CI, run bundle exec fastlane run_profile name:<profile>.

Profile '<name>' not found

Fix: Check fastlane/config/profiles/<name>.yml exists and is committed; names are lower-case with dashes. List them with bundle exec fastlane profiles.

No product flavors detected

Fix: init_project / setup read productFlavors from android/app/build.gradle(.kts). If flavors come from a plugin or script, answer n to “Use this Gradle task and glob?” and type the task.

No shared environments for android + ios

Fix: When both platforms are chosen, only environment names that exist under both android.environments and ios.environments are offered.

E-mail report not received

Fix: Check SMTP_*, TEST_ALERT_EMAIL_RECIPIENTS and notifications.email.enabled. Errors are logged, not fatal.

Was this helpful?

PreviousLanes and commands NextFAQ