‹ Platforms
Flutter troubleshooting
Fix Flutter plugin build and runtime errors by symptom.
| Symptom | Cause | Fix |
|---|---|---|
UnsatisfiedLinkError on an emulator | the engines are arm64-v8a only | run on a physical arm64 phone |
flutter pub get fails: version solving failed, naming bithuman and an SDK version | the plugin needs Dart 3.11.5 or newer | upgrade Flutter to a release that ships Dart 3.11.5 or newer |
| The app shows a refusal and asks for a secret | no API secret, or a rejected one | enter a valid API secret, or build with --dart-define=BITHUMAN_ |
Manifest merge fails on minSdk | the plugin needs minSdk 29, whichever model you use | set minSdk = 29 in android/ (Install) |
| Expression 2 runs slowly on Android, or a library is reported missing | the engines’ native libraries were compressed into the APK | set packaging { jniLibs { useLegacyPackaging = true } } (Install) |
MissingPluginException from pushAudio on Android | a plugin older than 2.6.36: Android had no pushAudio | update to 2.6.36, or send 24 kHz speech with playSpeakerPCM (Integrate into your app) |
| On iOS or macOS the lips move but nothing is heard | pushAudio drives the lips only | call audioStart(enableMic:, then playSpeakerPCM |
PlatformException(unsupported) from load | engine: names no engine; on iOS or macOS also Essence 2 below iOS 26 or macOS 26 | pass engine: or engine:; below iOS 26 or macOS 26, use Expression 2 |
load or an installer throws BithumanEntitlementException | bitHuman refused this API secret for this avatar (refused: true), or could not be asked while the device holds no recent yes for it (refused: false) | pass the owning account’s API secret; for refused: false, retry online (Flutter errors) |
| After a sign-out, the next account can still load the previous account’s avatars | the app kept the previous secret, or never cleared it | call BithumanAvatar. at sign-out, and pass each account’s own apiSecret |
| On iOS or macOS the avatar never becomes ready | no API secret, or a refused one: the Apple engines do not throw for it | pass a valid apiSecret: to load |
load throws BithumanModelRejected (MODEL_REJECTED) | the engine refused the avatar file | see Flutter errors |
A voice session ends with FORBIDDEN as it starts | the model needs an entitlement: gpt-realtime does (the session’s default before plugin 2.6.36) | pass model:, the default in plugin 2.6.36 and newer |
A voice session ends with PAYWALL, INSUFFICIENT_ or PLAN_REQUIRED | no minutes, no credits, or the plan does not include it | see Flutter errors |
pod install fails on iOS or macOS | the deployment target is below the plugin’s floor: iOS 16.4 and macOS 14.0 from plugin 2.6.37 (2.6.36: iOS 16.0, macOS 26.0) | raise the Podfile platform and the Runner targets: platform : and IPHONEOS_; platform : and MACOSX_ |
The macOS app does not start on macOS 14, naming libonnxruntime | Homebrew’s ONNX Runtime is built for macOS 15 | bundle an ONNX Runtime built for macOS 14 with the app, or require macOS 15 |
| The avatar shows no new frames after the app was in the background | after 60 seconds in the background (or with no frame taken) the session ends, billed to that point (plugin 2.6.37) | nothing to do: frames come back, in a new session, when the app is on screen again |
| The iOS or macOS build fails, naming the engines’ floor, after updating the plugin | Podfile.lock already resolves the pod and the app is below the floor (2.6.37: iOS 16.4, macOS 14.0) | raise the targets to the floor, keep $(inherited) in GCC_, then run pod install |
| The iOS or macOS build cannot find the engines | the bootstrap step was skipped | run scripts/ in the plugin’s folder, then build again |
A macOS link error names onnxruntime or llama | a Homebrew library the plugin links is missing | brew install onnxruntime; a plugin older than 2.6.37 also needs brew install llama. |