‹ 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-19, 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 |
create throws meteringRefused, or meteringRefusal is set after warmUp(): this account has no credits remaining (402) | the account is out of credits | top up, then start a new session; warmUp() does not throw, so check meteringRefusal after it |
pull() keeps returning nil right after feed() | frames arrive asynchronously, and Essence 2 hands out at most 25 a second | poll, or use frames() |
| An Expression 2 reply fed in real time freezes, then skips ahead, about every 1.6 s | the engine renders 1.6 s of audio at a time; the reply started before the next chunk could arrive | update to Swift package 2.20.6 or newer, where frames() waits until the reply can play through. On older packages, feed audio as soon as you have it and start the voice 0.75 s after the reply’s first frame |
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 |
404 (Agent not found for code) downloading a model | the agent does not belong to the account of the API secret you sent, or it has no model of the kind you asked for (model=expression-2 needs an Expression 2 agent, model=essence-2 an Essence 2 agent) | use the secret of the account that owns the agent, and check the code and model= under your agents |
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 |