‹ 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 Expression 2 below iOS 18 or macOS 15 (plugin 2.6.39), or Essence 2 below iOS 26 or macOS 26 | pass engine: or engine:; raise the app’s deployment targets to the model’s minimum (Expression 2: iOS 18.0, macOS 15.0) |
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 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 | the plugin’s ONNX Runtime was not staged, the plugin is older than 2.6.39 (those link Homebrew’s), or another ONNX Runtime is linked into the app (a duplicate-symbol error) | update to plugin 2.6.39 or newer, run scripts/ in the plugin’s folder, then pod install; remove any other ONNX Runtime (the onnxruntime-objc or onnxruntime-c pods, or your own libonnxruntime) |