‹ Platforms
Android troubleshooting
Fix Android SDK errors from Gradle, the secret and the device.
| Symptom | Cause | Fix |
|---|---|---|
Expression2Exception from create() naming the API secret | no secret set | call Expression2Credential. before fetch() and create() |
MeteringRefused on the first Essence 2 pull() | no secret set | call Essence2Credential. before fetch() and create() |
Essence2StoreException from fetch() | no secret was set when the store downloaded | call Essence2Credential. before fetch() |
Expression 2 renders slowly; acceleratorNote says no libQnnTFLiteDelegate. | the accelerator runtime was excluded, or legacy packaging is off | keep the dependency whole and set useLegacyPackaging = true |
The first Expression 2 create() after install is slow | the accelerator prepares the decoder once and keeps it; later launches reuse it | create on a background thread at app start; only the first launch after install pays it (and again after an SDK or OS update) |
Download refused with 401 | the avatar is private | set its owner’s API secret with Expression2Credential. or Essence2Credential. |
409 MODEL_ on download | the agent has no model of that kind yet | add the model, then retry |
Could not find ai. (or essence2-android) | bitHuman’s Maven repository is not in the build’s repositories | add the exclusiveContent block for https: to settings., as in Install |
Manifest merge fails on minSdk | essence2-android needs minSdk 29 | raise the module to 29 |
Unresolved reference: | the Android Gradle Plugin turns BuildConfig off by default | add buildFeatures { buildConfig = true } |
Unresolved reference 'MeteredDoorResolver' | the resolver’s public name is Essence2MeteredDoorResolver | you rarely need it: Essence2Credential. covers downloads. To pass a secret explicitly: import ai., then Essence2ModelStore(context, urlResolver = Essence2MeteredDoorResolver(secret)) |
Gradle stops with What went wrong: followed only by a Java version number (such as 25.0.4.1) | Gradle 8.11 cannot run on that JDK | set JAVA_HOME to JDK 17 or 21 and build again |
| The session is refused although you set a secret | BuildConfig. is empty | set bithuman. in local. or BITHUMAN_, then rebuild |
UnsatisfiedLinkError on an emulator | the engines are arm64-v8a only | run on a physical arm64 handset |