Loader plugins
Troubleshooting
When a bundle refuses to load, or the host refuses to build.
The loader distinguishes two kinds of failure so that an error points at the
responsible side. Bundle invalid means the bundle does not fit this host —
rebuild the bundle or extend the host. Loader build is broken means the host
build itself is wrong — the loader will reject every bundle until the host is
rebuilt correctly. On Android the underlying exception name and message follow
the title; the same messages appear in adb logcat -s FlitzLoader:*.
| 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 against a different SDK release than the host, or the host was built in a different mode (profile vs release) than the bundle targets. | Pin host and bundle to the same SDK tag and rebuild both. flitz status reports drift; flitz plugins configure confirms the plugin version for that tag. See SDK and plugin versions. |
Unsupported bundle version: <n> | The bundle's flitz_version is not 2 — it was produced by an incompatible flitz CLI. | Update the CLI and re-run flitz publish. |
Loader build is broken: flitz_loader_host_config.json is absent (or malformed) | The host was built without the build-time host-config step: on Android the Gradle plugin is not applied to this variant or the variant is not in enabledFlavors; on iOS the SwiftPM build-tool plugin is not enabled on the Runner target. | Apply the Gradle plugin and list the flavor, or enable FlitzAvailablePlugins in Run Build Tool Plug-ins. Rebuild the host. |
Loader build is broken: … NativeAssetsManifest.json … | The host's compiled flutter_assets/NativeAssetsManifest.json is unparseable or contains a forbidden asset kind (relative, system, executable). Usually a misbehaving hook-based FFI plugin. | Inspect the host build's NativeAssetsManifest.json; fix or update the FFI plugin; rebuild the host. See FFI. |
Bundle requires native asset ids not available in this host: Missing: <id> | The bundle calls an FFI plugin the host does not ship. | Add the plugin to the host's pubspec.yaml, flutter pub get, rebuild the host. |
| Error | Cause | Fix |
|---|
Bundle requires plugins not available in this host: Missing: <name> Available: … | The bundle's required_plugins names a plugin the host's pubspec.yaml does not declare. | Add the plugin to the host's pubspec.yaml, run flutter pub get, rebuild the host. The available-plugins asset is re-derived automatically. |
MissingPluginException from a method-channel call inside a running bundle | The plugin was not registered on the bundle engine. On iOS this almost always means registerPlugins(with:) is missing or empty. On Android the engine registers plugins reflectively, so it means the host's pubspec.yaml does not list the plugin and the up-front check was skipped. | iOS: override registerPlugins(with:) in AppDelegate and call GeneratedPluginRegistrant.register(with: engine). Android: add the plugin to pubspec.yaml and rebuild. |
Log line flitz_loader_available_plugins.json absent — required_plugins subset check skipped | The build-time hook that derives the list did not run. | Android: confirm the Gradle plugin is applied and the flavor is in enabledFlavors. iOS with SwiftPM: enable the FlitzAvailablePlugins build-tool plugin on the Runner target. |
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 late-created bundle engine. | Change the base class and make sure Info.plist's UISceneDelegateClassName names your SceneDelegate. See the iOS quickstart. |
| Symptom | Cause | Fix |
|---|
Every bundle is rejected on a host built with --debug | Bytecode runs only on an AOT engine. A debug host has no AOT and its guard refuses bundles before any compatibility check. | Build the host with --profile or --release. |
The iOS app does not link for the Simulator, or xcrun simctl cannot open a bundle | The engine and the loader ship arm64 device slices only. | Build for and install on a physical device. |
| The loader does nothing on a device with a different architecture | Supported targets are Android arm64 (arm64-v8a, API 29+) and iOS arm64 (16.0+). | Use a supported device; build Android with --target-platform=android-arm64. |
| Error | Cause | Fix |
|---|
Bundle file not found: <path> | The flitz://run?path= value is not readable. | Android: use an absolute path the app process can read, e.g. adb push to /data/local/tmp/. iOS: path is a bare filename inside the app's Documents directory — put the file there and pass only its name. |
Invalid bundle URL / Invalid URL with a parser reason (Missing 'url' query parameter, Only https:// download URLs are supported, path must be a leaf filename in Documents) | The authority is run or download but the parameters are wrong. | Fix the link: download needs a URL-encoded https:// value in url; run needs a non-empty path. See the URL scheme. |
| 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 to the host's scheme, and open the link on a build of an active flavor. |
| The scanner never starts the camera | Android: the CAMERA permission (auto-merged) was denied. iOS: NSCameraUsageDescription is missing from Info.plist. | Android: grant the permission; the loader's permission screen links to Settings. iOS: add the key as shown in the iOS quickstart. |
Unsupported QR code toast | The QR payload is not a run/download URL or a bare https:// URL. | Scan the QR code flitz publish prints, or encode an https:// bundle URL. |
| Message | Cause | Fix |
|---|
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 library module, or before com.android.application. | Apply it in android/app/build.gradle.kts, after com.android.application. |
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 loader-bearing flavor(s) 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 valid URL scheme | The scheme is not letter-led or contains characters outside letters, digits, +, -, .. | Fix the value. |
Cannot resolve FLUTTER_ROOT for the loader host config / Flitz SDK marker not found / platform_strong.dill not found | flutter.sdk in android/local.properties (or FLUTTER_ROOT) does not point at an installed Flitz SDK — typically stock Flutter. | Point the toolchain at the pinned SDK (flitz sdk path prints it). See Getting started. |
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; or flitzMavenToken is missing from ~/.gradle/gradle.properties. | Add the authenticated repository to allprojects too; run flitz plugins credentials --write. See the Android quickstart. |
An unresolved ${flitzUrlScheme} placeholder 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, which sets the placeholder. |
Still stuck? flitz status is the general entry point for toolchain problems —
see the CLI troubleshooting page.