Loader plugins
Troubleshooting
When the host refuses to build, a bundle refuses to load, or sign-in and access get in the way.
When a bundle does not fit the host, the loader names the responsible side in the error screen's title:
- Bundle invalid — the bundle does not fit this host. Publish a matching bundle, or add what it needs to the host.
- Loader build is broken — the host build itself is wrong. The loader refuses every bundle until the host is rebuilt correctly.
- Loader needs a newer SDK — the host was built with a Flitz SDK older than its loader-plugin version supports. Rebuild the host with a newer SDK.
Link, download, sign-in, and access errors have titles of their own; the sections below list them. The error screen shows the details under the title; on Android the underlying exception name and message follow it. On Android every error screen offers "Back". On iOS, "Back" appears only while the loader has a screen to return to, and at the panel level error screens also offer "Open panel". A failed download also offers "Retry". For logs:
- Android:
adb logcat -s FlitzLoader:* flutter:*shows the loader's progress and each error's title. The full details are on the screen. - iOS: filter Console.app by the subsystem
pl.leancode.flitz.loader. The loader also writesflitz_loader.loginto the app's Documents directory, starting a fresh one on every launch.
Host build errors
The SDK floor check runs before every build that includes the Flitz loader. Gradle
reports it from the flitzCheckSdkFloor<Variant> task; Xcode from the pod's
Flitz SDK floor check build phase or the SwiftPM FlitzLoaderSDKCheck
plugin. Every message starts with Flitz loader plugin <version>.
| Message | Cause | Fix |
|---|---|---|
…, but no Flutter SDK location resolves (…) | The build found no Flutter SDK: no flutter.sdk in android/local.properties and no FLUTTER_ROOT (Android), or no FLUTTER_ROOT in ios/Flutter/Generated.xcconfig (iOS; the SwiftPM plugin also accepts a FLUTTER_ROOT environment variable). | Build with the Flitz SDK's flutter on your PATH (flitz sdk path prints its root), which writes both files. See Getting started. |
…, but <path> is not a Flitz release SDK (no bin/internal/flitz.version). | The host is built with stock Flutter or another non-Flitz SDK. | Point the toolchain at the pinned SDK and rebuild. |
…; this build uses <tag> (iteration <n>). Pin a newer SDK with flitz sdk use <tag>, or use the plugin version flitz plugins configure prints for the pinned SDK. | The SDK is older than this loader-plugin version supports. | Do what the message says: pin a newer SDK, or use the plugin version flitz plugins configure prints. See SDK and plugin versions. |
Flitz loader plugin <version>: <path> is malformed (flitz_iteration must be a positive integer). | The SDK installation is damaged. | Reinstall it with flitz sdk use --force. |
Gradle (Android)
| Message | Cause | Fix |
|---|---|---|
Cannot query the value of this provider because it has no value available. while Gradle reads the settings | flitzMavenToken is not available to this build — a new machine, or CI. | Run flitz plugins credentials --write. In CI, set the ORG_GRADLE_PROJECT_flitzMavenToken environment variable. See the Android quickstart. |
HTTP 401 / Unauthorized while resolving pl.leancode.flitz.loader | The stored token is wrong or was replaced. | Run flitz plugins credentials --write again. |
Could not find pl.leancode.flitz:loader-android:<version> during the app build | The repository is in settings.gradle.kts but not in the top-level allprojects block, which the Flutter Gradle plugin's injected repositories take precedence over. | Add the authenticated repository to allprojects too. |
pl.leancode.flitz.loader must be applied to an Android application module that also applies the com.android.application plugin… | The plugin was applied to a module that does not apply com.android.application, such as a library module or the root project. | Apply it in android/app/build.gradle.kts. |
flitz.loader: applied but inactive — flitz { enabledFlavors } is empty… (lifecycle log) | No flavor is listed, so the loader is active in no variant. Not an error — but no build carries the loader. | List the flavors that should include the Flitz loader in flitz { enabledFlavors }. |
flitz { enabledFlavors } names unknown flavor(s): … Declared variant flavors: … | A listed name matches no produced variant: a typo, a bare dimension value instead of the combined flavor name, or the project declares no productFlavors at all. | Use the exact combined flavorName; declare flavors if the project has none. |
flitz { urlScheme } must be a lowercase URL scheme (letter-led; lowercase letters, digits, '+', '-', '.'; at most 32 characters); got '<value>'. | The scheme has an uppercase letter, does not start with a letter, contains other characters, or is longer than 32 characters. | Fix the value. flitz publish --schema follows the same rule. |
Manifest merger failed : uses-sdk:minSdkVersion … cannot be smaller than version 29 declared in library [pl.leancode.flitz:loader-android…] | The app's minSdk is below the loader's minimum. | Set minSdk = 29 in android/app/build.gradle.kts. |
An unresolved ${flitzUrlScheme} placeholder, or another ${flitz…} one, fails the manifest merge | The AAR is on the classpath without the Gradle plugin (a hand-written implementation dependency). | Remove the manual dependency and apply the Gradle plugin. |
flitz { signIn { clientId } } is not set. … | The signIn block has no clientId, or it is blank. | Set it to the client id Flitz gave you. |
flitz { panel { } } needs flitz { signIn { } }. | The panel level is set without sign-in. | Add the signIn block, or remove panel. |
flitz { panel { openingApp } } must be an app key (letters, digits, '_', '-'; at most 100 characters); got '<value>'. | openingApp is not an app key. | Use the key flitz apps list shows. |
flitz { launch } must be 'host' or 'panel'; got '<value>'. | launch has an unknown value. | Use "host" or "panel". |
flitz { launch = "panel" } needs flitz { panel { } }. | launch = "panel" is set without the panel level. | Add panel { }. |
CocoaPods and Xcode (iOS)
| Symptom | Cause | Fix |
|---|---|---|
pod install reports that the FlitzLoader specs require a higher minimum deployment target | The Podfile's platform is below iOS 16.0. | Set platform :ios, '16.0' in ios/Podfile and the Runner target's Minimum Deployments to 16.0. |
| A Simulator build does not link | The loader framework ships a device slice only. | Build for and install on a physical device. |
The app crashes at launch: dyld cannot load @rpath/FlitzLoader.framework/FlitzLoader | CocoaPods linked the framework but did not embed it in Runner.app. | Delete ios/Pods and ios/Podfile.lock, run pod install again, and rebuild. Check that Runner.app/Frameworks/FlitzLoader.framework exists. |
The app delegate does not compile: didInitializeImplicitFlutterEngine cannot be overridden | The delegate still carries the template's FlutterImplicitEngineDelegate method. | Remove the method and the conformance, and register your plugins in registerHostPlugins(with:). See the iOS quickstart. |
Load-time errors
| Error | Cause | Fix |
|---|---|---|
Platform dill hash mismatch: bundle=sha256:…, host=sha256:… (host SDK <tag>) (Android) / Platform dill hash mismatch — bundle was compiled against a different engine version. (iOS) | The bundle was built with a different SDK tag than the host. | Build the host and publish the bundle with the tag your project pins. If you moved the pin, rebuild and reinstall the host. To confirm the host's SDK, check that flutter --version points at flitz sdk path. |
Bundle requires native packages not available in this host: Missing: … Available: … | The bundle's app depends on a package with native code — a plugin, or an FFI package with a build hook — that the host does not ship. | Add the package to the host's pubspec.yaml, run flutter pub get, and rebuild and reinstall the host. |
Loader needs a newer SDK: This app was built with Flitz SDK <tag> (iteration <n>). FlitzLoader <version> needs iteration <N> or newer.… | The host was built with an SDK older than its loader-plugin version supports, from a build that skipped the build-time check (for example SwiftPM without the build-tool plugin). | Pin a newer SDK and rebuild the host, or use the plugin version flitz plugins configure prints. |
Unsupported bundle version: <n> | The bundle and the host's loader plugin use different bundle formats: the bundle came from an older flitz CLI, or the host was built with an older loader-plugin version. | Update whichever side is older: re-run the install script and flitz publish again, or update the loader plugin to the version flitz plugins configure prints and rebuild the host. |
Loader build is broken: … flitz_host.json is absent … (or malformed, or incomplete) | The host was not built with the Flitz SDK's flutter — for example it was built with stock Flutter. | Point your toolchain at the pinned SDK (flitz sdk path) and rebuild the host. |
Loader build is broken: … NativeAssetsManifest.json … | An FFI package's build hook produced native assets in a form the loader does not support, or the host's native-asset manifest is unreadable. | Update or replace the FFI package and rebuild the host. See FFI. |
Running bundles
| Symptom | Cause | Fix |
|---|---|---|
| On a debug host, a bundle passes the checks and then shows a blank screen (Android) or "Bundle engine did not start" after about 8 seconds (iOS) | Debug engines cannot run bundles. Android logs Bytecode execution requires an AOT-compiled engine under the flutter tag; iOS logs Cannot load bytecode as dynamic modules are disabled. | Build the host in release mode. A plain flutter run is a debug build. |
| "Bundle engine did not start" on a release host | The bundle's engine refused to start or, on iOS, drew no frame within 8 seconds. On Android the screen names the exception the engine threw while starting. | Rebuild the host with the pinned Flitz SDK. If the device log shows A script has already been loaded, something in the host links App.framework at load time; remove it. |
| "Cannot run bundles in this process" (Android) | The loader shares a process with your app's own Flutter engine: the app's manifest overrides android:process on the loader activities, or declares a FlutterActivity in the :flitz process. | Remove the override. See Where bundles run. |
MissingPluginException from a method-channel call inside a bundle (iOS) | registerPlugins(with:) is missing or empty, so the bundle's engine has no plugins. | Override it in AppDelegate and call GeneratedPluginRegistrant.register(with: engine). |
MissingPluginException in your own app's UI after adding the loader (iOS) | registerHostPlugins(with:) is not overridden, so your app's own engine has no plugins. | Override it and call GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry). |
A scene-aware plugin (for example FirebaseMessaging) hangs on init when a bundle is cold-launched from a link (iOS) | SceneDelegate does not extend BundleLoaderSceneDelegate, so the scene connection is never replayed into the bundle's engine. | Change the base class and make sure Info.plist's UISceneDelegateClassName names your SceneDelegate. See the iOS quickstart. |
| Firebase, WorkManager, or another SDK that starts itself is not initialized inside a bundle (Android) | The bundle runs in the :flitz process, where Android does not start those SDKs' ContentProviders. | Initialize the SDK from the bundle's own code, for example with Firebase.initializeApp. |
[core/duplicate-app] inside a bundle (iOS) | Your app configures Firebase natively, and the bundle calls Firebase.initializeApp(options: …) again. | In the bundle, call Firebase.initializeApp() without options. See Loading a bundle takes over the app. |
| A bundle does not run on a 32-bit Android device, or a release build crashes when the bundle starts | 32-bit ARM (armeabi-v7a) devices cannot run bundles. | Use an arm64 device or an x86_64 emulator. |
Links and downloads
| Error | Cause | Fix |
|---|---|---|
Invalid bundle URL / Invalid URL with a parser reason (on Android, for example, Missing 'url' query parameter or Only https:// download URLs are supported; on iOS, missing 'url' query item or scheme must be 'https' …) | The link is a download link, but its parameters are wrong. | Fix the link: it needs a URL-encoded https:// value in url. See the URL scheme. |
Download failed: HTTP <code> … | The server did not answer 200 with the archive. A 404 means the link is wrong, the publish or its app was deleted, or — for Run latest in the panel — the track has no build. Any other 401 or 403 means the server wants credentials the loader does not send. | Check the link, or use the one flitz publish printed. "Retry" repeats the download. |
| Download failed with a timeout (iOS) | On iOS the whole download must finish within 30 seconds. | Retry on a faster network. |
Download failed: Too many redirects (>5) for <url>, or a redirect to a non-https URL | The server redirects more than five times, or to plain HTTP. | Serve the bundle from an https:// URL with at most five redirects. |
| The link opens nothing at all | The scheme the link uses is not the scheme the host registered — for example flitz publish --schema acme against a host that registers flitz, or an Android variant not in enabledFlavors (which has no intent filter). | Match --schema (or schema: in flitz.yaml) to the host's scheme, and open the link on a build of an active flavor. |
| The landing page's button opens a different app, or Android asks which app to use | Another app on the device also registers the flitz scheme. | Give your host its own scheme and publish with a matching --schema. See Sharing the flitz scheme. |
| "Bundle file not found" | The file your native code handed to the loader is not readable. | Pass a readable file: on iOS a file URL inside the app's sandbox, on Android a path the :flitz process can read. |
Sign-in and access
Only a host with sign-in, an Enterprise feature, shows these screens, except Members only.
| Screen or symptom | Cause | Fix |
|---|---|---|
"Sign-in required": Sign-in is required to open builds in this app. | The sign-in browser was closed, or the approval was declined. | "Try again". |
| The sign-in page shows an error instead of asking you to sign in, and closing it shows "Sign-in required" | The client id is wrong, or the host's scheme is not the one the client id is registered for. | Check SignInClientID (iOS) or signIn { clientId } (Android), and that the host's scheme is the one you gave Flitz. |
| "Sign-in failed" | The sign-in service refused the sign-in, and the body names its error. No browser is available to sign in. means no browser could be shown. | Act on the error, then "Try again". |
| "Can't reach Flitz sign-in" | There is no network, or the sign-in service is unavailable. With sign-in, every load needs it, local files included. | "Retry" once you are online. |
| Android asks which app should open the sign-in result | Another app on the device uses the same scheme. | Pick your app. To stop the question, give your host a scheme of its own, and contact support to update your client id's registration. |
"Members only": This build opens only in its organization's app, for a signed-in member. | The build's app has download access Members only, and this host has no sign-in. | Open the build in your organization's host with sign-in, or have an Owner or Admin set the app's download access to Anyone with the link. |
"Can't open builds with this account": This build belongs to another organization. Sign out, then sign in with an account in its organization. | The signed-in account is not a member of the app's organization — for example because it was removed. | Open the panel with a flitz-panel link, sign out, and sign in with an account in the app's organization. |
A flitz-panel link does nothing | The host has no sign-in, so the loader ignores the link — or the link's scheme is not the host's (see Links and downloads). | Turn on sign-in. |
iOS: the app launches into its own UI despite Launch panel, and the log shows Launch panel needs a BundleLoaderSceneDelegate; the app launches into its own UI | The scene delegate does not extend BundleLoaderSceneDelegate. | Change its base class. See the iOS quickstart. |
| iOS: an error screen offers no "Back" | The loader has nothing to return to: your UI ran on the Flutter engine it shut down, or a bundle already drew its first frame. | Expected; relaunch the app. "Retry" still repeats a failed download, and at the panel level "Open panel" opens the panel. |
| The panel shows "Flitz is unavailable for your organization" | Your organization's Flitz license is not active. | The Owner reactivates it under Billing. |
| The panel shows "Can't open builds with this account" | Flitz refused the account — for example because it belongs to no organization. | "Sign out", then sign in with an account in your organization. |
| The panel shows "Can't reach Flitz" | There is no network, or Flitz did not answer. | "Retry" once you are online. |
Info.plist settings (iOS)
iOS checks the FlitzLoader URL type and dictionary when the app runs, not
when it builds. A mistake makes the app launch into your own UI with no
"Open panel", and every load and every opening of the panel shows Loader
build is broken, naming the first problem:
| Message | Fix |
|---|---|
Info.plist has no CFBundleURLTypes entry named FlitzLoader. | Sign-in is on, but no URL type is named FlitzLoader. Name the loader's URL type FlitzLoader — see Register the URL scheme. |
The FlitzLoader URL type lists no scheme. | List your scheme in that URL type's CFBundleURLSchemes. |
The FlitzLoader Panel needs SignInClientID. | Add SignInClientID, or remove Panel. |
The FlitzLoader Panel is not a dictionary. | Make Panel a dictionary. |
The FlitzLoader Panel OpeningApp '<value>' is not an app key. | Use the key flitz apps list shows. |
The FlitzLoader Launch '<value>' is neither host nor panel. | Use host or panel. |
The FlitzLoader Launch panel needs the Panel dictionary. | Add Panel, or remove Launch. |
See Info.plist keys for every key.
Still stuck? flitz status is the general entry point for toolchain problems —
see the CLI troubleshooting page. To report a problem,
contact support.