Troubleshooting

Upload errors

APK limit reached (plan limit)

✗ Upload blocked — you've reached your APK limit for this app.
✗ Free plan: 5 APKs per app. Upgrade in the AppFlight mobile app.
✗ Settings → Subscription → Upgrade to First Class

Exit code: 8

Cause: Your account has hit the APK-per-app limit for your current plan. The Economy (free) plan allows 5 APKs per app. Older builds are preserved, but no new ones can be added until you upgrade or delete existing builds.

Fix:

• Upgrade: Open the AppFlight mobile app → Settings → Subscription → Upgrade to First Class
• Check your plan: Run appflight whoami — the plan: field shows your current tier

Run with --verbose to see the full server response for more detail:

appflight upload --flavor stage --verbose

Version already exists

✗ Version 1.0.0 already exists for com.myapp.stage.
✗ Bump the version or use --version.

Cause: You've already uploaded this version. AppFlight doesn't allow overwriting an existing build.

Fix: Bump the version and rebuild, or override at upload time:

appflight upload --flavor stage --version 1.0.1

appflight upload --flavor stage --version 1.0.1

App not found

✗ App not found on AppFlight: com.myapp.stage

Cause: The package name in appflight.json doesn't match any app registered on AppFlight. The app must be created in the AppFlight mobile app before the CLI can upload to it.

Fix:

1. Open the AppFlight mobile app and create the app with the exact same package name
2. Or check appflight.json for a typo in packageName

Package name already taken

✗ An app with package name "com.myapp.stage" already exists.

Cause: Another AppFlight user has already registered this package name. Package names are unique across the entire platform — the same rule that applies on the Google Play Store.

Fix: You cannot upload to a package name owned by someone else. If this is your app, contact AppFlight support or use a different package name.

APK not found

✗ APK not found at build/app/outputs/flutter-apk/app-stage-release.apk
✗ Did you forget to run `flutter build apk --flavor stage --release`?

# Build first
flutter build apk --flavor stage --release

# Or point directly at your APK
appflight upload --flavor stage --file path/to/app.apk

✗ APK not found at android/app/build/outputs/apk/stage/release/app-stage-release.apk
✗ Did you forget to run `cd android && ./gradlew assembleStageRelease`?

# Build first
cd android && ./gradlew assembleStageRelease

# Or point directly at your APK
appflight upload --flavor stage --file path/to/app.apk

APK path flavor mismatch

The --flavors flag uses the flavor name to derive the APK path. If your build output doesn't follow the expected pattern, the derived path may not match.

Fix: Edit apkPath in appflight.json to match your actual build output:

"prod": {
  "packageName": "com.myapp",
  "apkPath": "build/app/outputs/flutter-apk/app-prod-release.apk"
}

"prod": {
  "packageName": "com.myapp",
  "apkPath": "android/app/build/outputs/apk/prod/release/app-prod-release.apk"
}

Permission denied (org apps)

✗ Only admins and developers can upload to organization apps.

Cause: Your account has the member role in the organization. Only admin and developer roles can upload builds.

Fix: Ask an admin to update your role in the AppFlight mobile app → Settings → Team.

Auth errors

Not logged in

✗ Not logged in. Run `appflight login` or set APPFLIGHT_API_KEY.

Fix:

# Interactive login
appflight login

# Or set env var (CI/CD)
export APPFLIGHT_API_KEY=appflight_xxxxxxxxxxxx

API key invalid or revoked

✗ API key rejected. Check it and try again.

Cause: The key was revoked in the AppFlight mobile app, or copied incorrectly.

Fix:

1. Go to AppFlight app → Settings → API Keys
2. Check if the key is still active (not revoked)
3. Generate a new key if needed, then run appflight login again

Init errors

Invalid package name format

✗ Invalid: "com.MyApp.Stage"
  Must be lowercase, dot-separated, at least 2 segments.
  Example: com.mycompany.myapp

Rules:

• All lowercase
• Dot-separated with at least 2 segments
• Letters, digits, and underscores only
• Cannot be com.example.app

Spaces after commas in --flavors

# Wrong — shell splits on the space, second package is dropped silently
appflight init --flavors stage:com.myapp.stage, prod:com.myapp

# Correct — no spaces
appflight init --flavors stage:com.myapp.stage,prod:com.myapp

appflight.json already exists

⚠ appflight.json already exists. Use --force to overwrite.

Fix:

appflight init --flavors stage:com.myapp.stage,prod:com.myapp --force

Still stuck?

Run with --verbose for detailed output, or check appflight --help for all available flags.

If the issue persists, reach out through any of these:

When filing a GitHub issue, include the output of appflight upload --verbose (or whichever command failed) — it makes diagnosis much faster.