Troubleshooting
Build failures, authorization and licensing, network, and offline behavior — each mapped to a remedy.
Run flitz status first. It is the entry point for every
"why isn't this working" question: it checks your account, project, plugins,
and CLI, and each finding names the command that fixes it. This page maps the
failures you might hit to their remedies, by class. The exit code tells you the
class — see Exit codes.
Build failures
Both compilers print their own output verbatim above the message; re-run with
-v to watch them live. All build failures are exit 5.
kernel compilation failed
flutter build bundle rejected the app — an ordinary Dart or Flutter compile
error. The compiler's diagnostics are printed above the message.
Fix what the compiler names, exactly as you would for a normal build, and re-run.
bytecode compilation failed
dart2bytecode rejected the kernel. This is the step unique to Flitz: it
compiles your app to bytecode and validates it against the dynamic interface
that ships inside the pinned SDK. There are three documented causes:
Dynamic Modules prohibit dynamic-typed invocations. Give the value a
concrete type, or make the call through a typed interface, so the compiler
can resolve it statically.
The app (or a dependency) references a platform API the pinned SDK does not
contain. Confirm with flitz status that the pinned SDK is the one you
meant; if the API is newer, moving the pin is a deliberate decision
(flitz sdk use <newer tag>).
A dependency reaches a dart:ffi API — often a private member — that is not
part of the declared interface. Move the use behind an API the interface
exposes. See Compatibility → FFI.
The hint on the failure names all three so the likely explanation sits next to the compiler's own output. Flitz is built on Dart's upstream-experimental Dynamic Modules, and this validation is where that experimental surface makes itself felt.
SDK problems
| Symptom | What it means | Remedy |
|---|---|---|
no SDK is pinned for this project (exit 1) | No flitz.yaml with an sdk: key in the directory you ran flitz in. | flitz sdk use latest here. The pin is read from the working directory, not from --app. |
the pinned SDK <tag> is not installed (exit 1) | The project pins a tag this machine has not fetched, and you were non-interactive without --yes (or declined). | flitz sdk use, or pass --yes to let publish fetch it. |
SDK <tag> is missing a build tool (⚠ in status) | The cached tree passed the marker check but is damaged. | flitz sdk install --force <tag>. |
SDK <tag> has no marker for <host> (✗ in status) | The cache entry is not a valid SDK for this host. | flitz sdk use <tag>. |
invalid release tag: <value> (exit 1) | The tag argument does not match the <flutter-version>-flz.<N> grammar. | flitz sdk releases to see what is published. |
unsupported host (exit 1) | You are on a host other than linux-x64 or macos-arm64. | The CLI runs only on the supported hosts. |
A cached SDK never fetches from Google's artifact CDN — the archive ships a
pre-populated bin/cache/ — so a build against a cached SDK works with no
connectivity.
Authorization and licensing
All exit 3. Authorization answers are never reported as network failures, and an inactive license never as "try again shortly" — it does not become active by waiting.
| Symptom | What it means | Remedy |
|---|---|---|
you are not logged in to Flitz | No stored sign-in and FLITZ_APIKEY unset. | flitz login, or set FLITZ_APIKEY for CI. |
your Flitz session has ended | Your credential was expired, revoked, or rejected. | flitz login again. |
the Flitz credential was rejected | The service refused the credential. | flitz login; check FLITZ_APIKEY in CI. |
your organization's Flitz license is not active | The license, not your credential. | Contact your organization administrator. Waiting does not help. |
Flitz key management requires an interactive session | An apikey mutation was attempted under FLITZ_APIKEY. | Run it from an interactive session after flitz login. See flitz apikey. |
Network and service
All exit 4. Reads retry with backoff before failing; the message names what was unreachable.
| Symptom | What it means | Remedy |
|---|---|---|
the Flitz service returned HTTP <status> | A persistent 429/5xx or an unexpected status after retries. | Retry; report it if it persists. |
the service could not be reached | DNS, TLS, or transport failure. | Check connectivity, then retry. |
the downloaded <tag> SDK has digest … , expected … | A downloaded archive failed its SHA-256 check. | Retry; report it if it persists. The cache is untouched — the partial is discarded. |
the bundle destination is already occupied | A previous, interrupted publish reserved that object path. | Re-run flitz publish; it allocates a new one. |
the bundle upload failed: … | The upload transport failed. | Re-run flitz publish. |
A failed or mismatched SDK download never replaces, truncates, or deletes an already-installed SDK.
Deeplink and QR
| Symptom | What it means | Remedy |
|---|---|---|
| A generic phone camera won't open the QR | The deeplink uses the flitz:// scheme, which only a host with the loader registers. | Scan it from inside a host that has the loader embedded, or open the landing-page link and use the button/QR there. |
| A host ignores the deeplink | The host registered a different scheme than the bundle was published with. | Publish with --schema <scheme> matching the host. See URL scheme. |
platform_dill_hash mismatch at load time | The host and the bundle were built against different SDK tags. | Build both against the same tag. See Compatibility. |
Offline behavior
There is no --offline flag, because there is nothing to opt into — the CLI
degrades on its own.
flitz statusturns its four network rows into? unknown (offline)and changes nothing else. It still exits 0.- Local
sdkcommands —list,path,remove— never touch the network and work unchanged. - A cached SDK builds fully offline. Re-running
flitz sdk usefor a tag already in the cache does no network I/O, and the build tools inside the SDK do not reach out either. - The update notice fails silently when offline and prints nothing.
What needs the network is the licensed set: login, sdk install/use/releases,
plugins, apikey, and publish. Revocation governs those — new downloads,
new plugin tokens, new publishes — and takes effect within minutes. Bytes
already on disk keep working; that is inherent to a self-contained toolchain.
If flitz reports a release-tag mismatch, the pinned SDK and the rest of the
toolchain have drifted — re-run flitz sdk use (no argument) to realign on the
project's committed pin.
Still stuck?
When the CLI prints unexpected error — please report this, it appends a
secret-free bug-report capture
that is safe to paste as-is. Include it when you report the problem.