‹ Platforms
Swift troubleshooting
Fix Swift package errors on iPhone, iPad and Mac, by symptom.
iOS
| Symptom | Cause | Fix |
|---|---|---|
create throws meteringRefused (C: be_ returns -3): no API secret was found | no secret | call Essence2Credential. / Expression2Credential., or set BITHUMAN_ in the scheme |
| the API secret was rejected | revoked or mistyped secret; from 2026-10-12, a Free account | create a new one under API secrets; on Free, choose a plan |
| cannot reach bitHuman to verify your credential | no network at first contact | fix the network, then create again |
pull() keeps returning nil right after feed() | frames arrive asynchronously, and Essence 2 hands out at most 25 a second | poll, or use frames() |
crash in __cxa_finalize when the app quits | Essence2Engine. (C: be_) was not called | call it from applicationWillTerminate |
unable to resolve module dependency: on a Simulator build | the default destination also builds x86_64 | add ARCHS=arm64, or set EXCLUDED_ in the target |
expression is 'async' but is not marked with 'await' on player. | Xcode 26 imports an async overload | call player. |
duplicate symbol naming MLX at the final link, or Essence 2 memory rising in a long session | an older Swift package | raise from: to the version on Downloads & versions, then swift package update |
a link error naming BithumanEngineProtocol | that product was added beside Expression2, which already contains it | depend on Expression2 only |
401 MISSING_ downloading a model | the agent code and model= do not match a sample avatar | check the code, or send your API secret for your own agent |
macOS
| Symptom | Cause | Fix |
|---|---|---|
refusing to serve: | no secret in this shell or scheme | export BITHUMAN_, or set it in the scheme |
| cannot reach bitHuman to verify your credential in a Mac app | App Sandbox blocks outgoing connections | tick Outgoing Connections (Client) under App Sandbox |
create throws before engine ready | the model files are missing | run ./setup.sh from the example folder, so Model/ holds the three files |
| The first run is slow | the engine is prepared for this Mac once | keep Model/staged/ between runs |