Build and Preview Troubleshooting

Before you start

• App ID and build or preview job ID
• Approximate failure time
• Admin access for detailed logs when available

Configure and verify

1. Identify the failing stage

   Read the user-facing status and note whether failure occurred while preparing source, copying assets, running pub get, building APK, building AAB, publishing preview, or copying artifacts.

2. Check saved configuration

   Confirm valid URL, identifier, version, assets, signing passwords, external SDK files, and required module fields.

3. Review admin diagnostics

   Admins can reveal build history and logs or Flutter preview worker events. Use the first concrete error, not the final generic failure line.

4. Check worker prerequisites

   Verify PHP CLI, Flutter, Android SDK, Java, write permissions, outbound dependency access, storage space, and the build lock.

5. Retry transient locks carefully

   The workers retry recognized Flutter SDK cache locks. On Windows, OneDrive or antivirus can hold generated files; use a fresh build source folder and avoid editing active output.

6. Submit a safe support ticket

   Include IDs, timestamps, stage, and redacted log excerpt. Never include keystore passwords, OAuth secrets, service-account JSON, or bearer tokens.

Common signals

Waiting for Android build lock

Another build is compiling on this worker

engine.realm or Flutter cache locked

Another Flutter process or scanner holds SDK cache files

Keystore validation failed

JKS, alias, or password mismatch

google-services package mismatch

Firebase file was downloaded for another package

Flutter preview directory locked

Browser, OneDrive, antivirus, or another worker holds generated assets

Artifact missing

Compilation or final copy did not complete

Do not delete shared toolchains mid-build

Test before release

• Failure stage is known
• First actionable error is captured
• Secrets are redacted
• Transient retry was bounded
• Support ticket includes IDs and time