‹ Overview
Troubleshooting
Where to fix a problem on each platform, and the common session errors.
Every platform and recipe page ends with a Troubleshooting table for its own problems; this page links them all, then covers common session errors.
By platform
| Platform | Its Troubleshooting table |
|---|---|
| iOS & iPadOS | Swift package on iPhone and iPad |
| macOS | Swift package on the Mac |
| Android | Android SDK |
| Flutter | Flutter plugin |
| Web | Web embed |
| Python | Python SDK |
| CLI | CLI |
| LiveKit | LiveKit plugin |
| Pipecat | Pipecat service |
| REST API | REST · every error code: Errors |
By task
| Task | Its Troubleshooting table |
|---|---|
| Create an avatar | Create an avatar · creation errors: Errors |
| A voice agent | Voice agent |
| A companion app | Companion app |
| A kiosk | Kiosk |
| A talking video | Talking video |
| Persona and gestures | Persona · Gestures |
| Claude, Cursor and other MCP clients | MCP server |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The first session on a new agent is slow | capacity is starting | wait: up to tens of seconds the first time; later sessions connect in seconds. If sessions keep failing, check status.bithuman.ai |
| The agent will not launch right after creation | it is not ready yet, or its model is still being prepared for serving | poll until ready; retry the first session after a short wait |
409 MODEL_ | the session asked for a model the agent does not have | check supported_; add the model |
The session ends at once with avatar_ | a ?model= in the URL named a model the agent does not have | remove ?model=, or add the model |
404 on /speak or /add-context | the agent has no live session | start a session first |
| No microphone prompt in an embed | the iframe lacks allow="microphone *" | add it (Web) |
| In a room with several agents, the avatar stays silent for one | the avatar follows the agent that called AvatarSession. | start the avatar from the agent it should speak for |
Creation stays at lip_sync for a long time | that is the training step for Essence 2 and Expression 2 (about 2–2.5 hours) | keep polling |
Creation errors and their fixes are on Errors.
Plan and credit refusals
Every SDK and the CLI refuse a render or session the same way, with the service’s reason in the message (the CLI exits 77). Each code, its link field and the exact wording: Errors.
| The message says | Cause | Fix |
|---|---|---|
| API and SDK access starts at the Creator plan | from 2026-10-12, a Free account’s API secret (403 PLAN_) | choose a plan |
| the API secret was rejected, was not accepted or account suspended | a revoked or mistyped secret; from 2026-10-12, an older SDK or CLI also says this for a Free account | create a new one under API secrets; if a new secret is refused too, choose a plan |
| Your … plan allows N cloud avatar sessions at once, and N are running (N/N) | the plan’s concurrent cloud sessions (403 CONCURRENCY_); every running session holds a slot until it ends | terminate a session to free its slot at once, or choose a plan |
as many agents as its plan allows, or 403 AGENT_ | a new agent would pass the plan’s agent limit; existing agents keep working | delete an agent, or choose a plan |
| no credits remaining or out of bitHuman credits | no credits left (402 INSUFFICIENT_) | top up on the Creator plan or higher |
| this account is suspended | runtime access is suspended (403 RUNTIME_) | contact support; a plan change does not clear it |
Voice agent
The voice agent, with the CLI or the Python example.
| Symptom | Cause | Fix |
|---|---|---|
bithuman run exits 69: livekit-server 1.bithuman run“ | The CLI needs livekit-server 1.13 or newer | brew upgrade livekit (macOS), or reinstall the CLI (Linux: its download includes one) |
| The video stalls for 1–2 s every 15 s, or a LiveKit Meet tile goes black | livekit-server older than 1.9.12: the browser leaves and rejoins the room every 15 s | brew upgrade livekit (macOS) or curl -sSL https: (Linux), then restart livekit-server |
livekit-server not found (exit 69) | LiveKit is not installed | brew install livekit (macOS) or curl -sSL https: (Linux) |
| The avatar never appears | No or invalid API secret | CLI: bithuman login. Python example: set BITHUMAN_ in .env |
The avatar never appears; the terminal shows essence-2: | Essence 2 unpacks its avatar with ffmpeg | sudo apt install -y ffmpeg, then run again |
| The page says it could not connect | livekit-server --dev is not running | Start it, then click Start again |
| Nothing happens after joining | livekit-server --dev or agent.py is not running | Start both, livekit-server first |
| Another device on your network cannot join | --dev listens on localhost only | livekit-server --dev --bind 0.; other browsers also need HTTPS for the microphone |
On a Mac, your own page with no microphone, on the same machine as the avatar, fails with could not establish pc connection | Chrome hides the machine’s local addresses until the page has microphone permission | call navigator. before connecting, or open the page from another device |
OSError: | the system library is missing | sudo apt install libportaudio2 (Debian, Ubuntu) |
cv2. | the headless OpenCV build won the install | pip install --force-reinstall --no-deps opencv-python |
error: | outside the virtualenv | . |
| No microphone input on macOS | the terminal has no microphone permission | System Settings → Privacy & Security → Microphone |
Next
- Models · Agents API · Errors
This section moved: docs.bithuman.ai/resources/troubleshooting#troubleshooting
This section moved: docs.bithuman.ai/resources/troubleshooting#troubleshooting
This section moved: docs.bithuman.ai/resources/troubleshooting#troubleshooting
This section moved: docs.bithuman.ai/resources/troubleshooting#troubleshooting