Troubleshooting
Build failures, SDK problems, authorization and licensing, network, links, 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 most findings name the command that fixes them. 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
The compiler's own output is printed verbatim above the message; re-run with
-v to watch it live. Both compile failures are exit 5.
kernel compilation failed
The app does not compile — 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.
An SDK older than the CLI
If the output above kernel compilation failed says
Could not find an option named "--no-build-code-assets"., or publish ends
in an unexpected error that mentions flitz_host.json, the pinned SDK is older
than your flitz CLI supports.
Fix: pin a current release with flitz sdk use latest (or a tag from
flitz sdk releases), then rebuild and reinstall the host with that SDK so
host and bundles match again.
bytecode compilation failed
This step is unique to Flitz: it checks that your app and its dependencies use only the Dart platform APIs a bundle may use with the pinned SDK. Its two causes:
The app, or a dependency, references a Dart or Flutter platform API that
the pinned SDK does not contain — typically an API from a newer Flutter
version. Confirm with flitz status that the pinned SDK is the one you
meant; if you need the newer API, moving the pin is a deliberate decision
(flitz sdk use <newer tag>), and the host must be rebuilt with it.
A dependency reaches a dart:ffi API — often a private member — that
bundles cannot call. Move the use behind a public dart:ffi API. See
Compatibility.
The failure hint also names a dynamic call as a cause. Dynamic calls
compile, so look at the two causes above.
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 --dir. |
the pinned SDK <tag> is not installed (exit 1) | The project pins a tag this machine has not fetched, and you declined the download. | flitz sdk use, or pass --yes to let publish fetch it. |
The pinned SDK <tag> is not installed. Download it now …? — and there is no terminal to ask on (exit 1) | publish ran without a terminal and without --yes. | flitz sdk use, or pass --yes. |
invalid release tag: <value> (exit 1) | The tag does not have the <flutter-version>+flz.<N> shape. | flitz sdk releases to see what is published. |
the Flitz service returned HTTP 404: release not found from sdk use or sdk install (exit 4) | No release has that tag. Retrying does not help, whatever the hint says. | Copy the tag exactly from flitz sdk releases, + included. |
release <tag> has no SDK for host <host> (exit 1) | The release has no build for this machine. With sdk use, the pin was already written. | Use a Linux x64 or Apple-silicon macOS machine. |
another flitz is installing the <tag> SDK (exit 2) | Another flitz on this machine held the install for over ten minutes. | Let it finish, then retry. |
downloading the <tag> SDK failed after 5 resumptions: … (exit 4) | The download kept breaking off. | Re-run; the transfer resumes where it stopped. |
the <tag> SDK archive could not be unpacked: … (exit 4) | The system tar could not unpack the .tar.xz archive. | Install xz support for tar (the xz-utils package on Debian and Ubuntu), then retry. |
SDK <tag> is missing a build tool (⚠ in status) | The cached tree 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 machine. | flitz sdk use <tag>. |
FlutterRootVerificationException: FLUTTER_ROOT (<path>) is not a valid Flitz SDK. in publish (exit 1) | The cached SDK is damaged. | flitz sdk install --force <tag>. |
<path>/flitz.yaml is not valid YAML (exit 1), or it does not contain a YAML mapping, or a key is not a string | The file does not parse, or a value is not a string. | Fix it, or delete it and run flitz sdk use <tag> again. It holds sdk: <tag>, plus the optional app:, track:, and schema: and anything you added. |
flitz: unsupported host: <os> <arch> from the install script (exit 1) | Flitz is built for Linux x64 and Apple-silicon macOS; other machines are not yet supported. | Use a supported machine. |
A cached SDK's own flutter and dart need no network, so building the host
works offline.
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 sign-in expired or was revoked. | flitz login again. |
the Flitz credential was rejected | The service refused the credential. | flitz login; in CI, check FLITZ_APIKEY. |
your organization's Flitz license is not active | The license, not your credential. | Your organization's Owner restores it from the Billing page of the portal, by subscribing or by fixing the payment after a trial or payment lapse. If you are not the Owner, ask them. Waiting does not help. |
Flitz key management requires an interactive session, publish deletion requires an interactive session, or app management requires an interactive session | An apikey mutation, publishes delete, or an apps change was attempted under FLITZ_APIKEY. | Run it where FLITZ_APIKEY is not set, after flitz login. See flitz apikey. |
flitz status shows ? license — unknown (offline) while you are online | Your sign-in has ended or was rejected; status cannot tell that apart from being offline. | Run any licensed command, such as flitz sdk releases, to see the real cause — usually flitz login fixes it. |
Network and service
All exit 4. Reads retry with backoff before failing; the message names what was unreachable.
| Symptom | What it means | Remedy |
|---|---|---|
the request to <host> failed after 5 attempts: <cause> | DNS, TLS, a timeout (no response within 30s), or a service that kept failing. | Check connectivity, then retry. |
the request to <host> failed: <cause> | A request that is sent only once, such as registering a publish, did not get through. | Re-run the command. |
the service asked to wait <n>s before retrying (HTTP 429) (or 503) | The service is busy and asked for a longer pause than the CLI waits out. | Retry after that delay. |
the Flitz service returned HTTP <status>, sometimes followed by : <message> | The service refused the request. A 404 from sdk use or sdk install (…HTTP 404: release not found) means the tag does not exist. | Fix the request as above; otherwise retry, and report it if it persists. |
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 upload for <stem> failed: … | The bundle upload did not complete. When the message ends in no response within 30s, it ran out of time: the upload must finish within 30 seconds. | Re-run flitz publish, from a faster network if it timed out, or trim large assets. |
the bundle destination for <stem> is already occupied | This publish's upload destination already held an object. | Re-run flitz publish; every publish gets a new destination. |
| A publish fails with a service error in an organization that uses customer bundle storage | The connection to your bucket may be broken, for example by a changed bucket policy. The message does not name the storage. | Ask your cloud admin to check Flitz's access, or contact support. |
A failed or mismatched SDK download never replaces, truncates, or deletes an already-installed SDK.
Apps and tracks
All exit 1.
| Symptom | What it means | Remedy |
|---|---|---|
Every CI publish lands on the Unassigned track | The job checks out a detached commit, which has no branch. | Pass --track "$BRANCH_NAME", or set track: in flitz.yaml. |
App <key> does not exist in your organization. Create it? — and there is no terminal to ask on | --app or app: names a key your organization does not have. | Check the key for typos; pass --yes to create the app. |
app <key> is archived / app <key> is deleted | The app refuses new publishes. | flitz apps unarchive <key>, or flitz apps restore <key> within 30 days of the delete. |
<dir> is an app directory, not an app key | --app takes a key, not a folder. | Pass the folder as --dir <dir>. |
body/name must NOT have more than 120 characters (or versionName, comment) | A publish label is over its limit. | Shorten it and re-run. |
| A track link stopped working after an app was renamed | Track links contain the app key. | Take the new link from flitz tracks, and update app: in flitz.yaml. |
See flitz apps, flitz tracks, and flitz publishes for the commands.
Links on the device
| Symptom | What it means | Remedy |
|---|---|---|
| Tapping the landing page's button does nothing | No app on the device handles the link's scheme. | Install your host — the build of your app that includes the Flitz loader — on the device. If your host registers a custom scheme, publish with --schema set to it. |
| 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 when the bundle loads | The host and the bundle were built against different SDK tags. | Rebuild the host with the project's pinned SDK, or publish with the SDK the host was built with. See Loader troubleshooting. |
Loader needs a newer SDK when the bundle loads | The host's SDK is older than its loader plugin supports. | Pin a newer SDK and rebuild the host, or use the plugin version flitz plugins configure prints. See Loader troubleshooting. |
| The loader shows Members only or Can't open builds with this account | The app is set to Members only, and the host has no sign-in, or you are signed in with an account outside the organization. | See Loader troubleshooting → Sign-in and access. |
| A link that used to work now answers 404, or the loader shows Download failed with HTTP 404 | The publish was deleted, its app was deleted, or — for a track link — the app's key was renamed. | Restore a deleted app with flitz apps restore <key> within 30 days; take the new track link from flitz tracks. A deleted publish cannot come back: publish again. |
publish printed its links, but the publish stays pending, then turns abandoned, and its links do not open | The CLI is older than the current publish flow, in which the CLI itself marks a publish complete. | Update the CLI by re-running the install script, then publish again. |
Flags that surprise
| Symptom | What it means | Remedy |
|---|---|---|
There is one verbosity level; pass -v (or --verbose) at most once. although you passed no -v, or stack traces appear unasked | The CLI looks for v in every short option, including an attached -DKEY=VALUE, so a define such as -DAPI=https://dev.vendor.io reads as -v. | Write -D KEY=VALUE with a space, or --dart-define=KEY=VALUE. |
Offline behavior
There is no --offline flag, because there is nothing to opt into — the CLI
degrades on its own.
flitz statusshows its network rows as? <check> — unknown (offline)and changes nothing else. It still exits 0.- Local commands —
sdk list,sdk path,sdk remove,completions,logout, and--version— never touch the network and work unchanged. - A cached SDK's
flutteranddartwork offline, so you can build the host without a connection. - The update notice fails silently when offline and prints nothing.
What needs the network: login, and the licensed commands sdk install,
sdk use, sdk releases, publish, publishes, tracks, apps, plugins,
and apikey.
sdk use contacts the service even when the tag is already cached, and
publish always registers the publish before it builds. What is already on
disk — cached SDKs, the hosts you built — keeps working.
Still stuck?
When the CLI prints unexpected error — please report this, it appends a
bug-report capture built to be
safe to paste. To report it, contact support and send the capture with
the command you ran.