Docs index: /llms.txt · every page as Markdown: add .md

‹ Platforms

Swift troubleshooting

Fix Swift package errors on iPhone, iPad and Mac, by symptom.

iOS

SymptomCauseFix
create throws meteringRefused (C: be_essence2_create returns -3): no API secret was foundno secretcall Essence2Credential.set / Expression2Credential.set, or set BITHUMAN_API_SECRET in the scheme
the API secret was rejectedrevoked or mistyped secret; from 2026-10-19, a Free accountcreate a new one under API secrets; on Free, choose a plan
cannot reach bitHuman to verify your credentialno network at first contactfix 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 creditstop 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 secondpoll, or use frames()
An Expression 2 reply fed in real time freezes, then skips ahead, about every 1.6 sthe engine renders 1.6 s of audio at a time; the reply started before the next chunk could arriveupdate 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 quitsEssence2Engine.quiesceAll() (C: be_essence2_quiesce_all) was not calledcall it from applicationWillTerminate
unable to resolve module dependency: 'Expression2' on a Simulator buildthe default destination also builds x86_64add ARCHS=arm64, or set EXCLUDED_ARCHS[sdk=iphonesimulator*] = x86_64 in the target
expression is 'async' but is not marked with 'await' on player.scheduleBuffer(reply)Xcode 26 imports an async overloadcall player.scheduleBuffer(reply, completionHandler: nil)
duplicate symbol naming MLX at the final link, or Essence 2 memory rising in a long sessionan older Swift packageraise from: to the version on Downloads & versions, then swift package update
a link error naming BithumanEngineProtocolthat product was added beside Expression2, which already contains itdepend on Expression2 only
401 MISSING_AUTH downloading a modelthe agent code and model= do not match a sample avatarcheck the code, or send your API secret for your own agent
404 (Agent not found for code) downloading a modelthe 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

SymptomCauseFix
refusing to serve: no API secret was foundno secret in this shell or schemeexport BITHUMAN_API_SECRET=…, or set it in the scheme
cannot reach bitHuman to verify your credential in a Mac appApp Sandbox blocks outgoing connectionstick Outgoing Connections (Client) under App Sandbox
create throws before engine readythe model files are missingrun ./setup.sh from the example folder, so Model/ holds the three files
The first run is slowthe engine is prepared for this Mac oncekeep Model/staged/ between runs