# Troubleshooting

URL: https://docs.bithuman.ai/resources/troubleshooting

> Where to fix a problem on each platform and recipe, what a working live session looks like, and the fixes for 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 the live session itself.

## By platform

| Platform | Its Troubleshooting table |
|---|---|
| iOS & iPadOS | [Swift package on iPhone and iPad](https://docs.bithuman.ai/platforms/ios#troubleshooting) |
| macOS | [Swift package on the Mac](https://docs.bithuman.ai/platforms/macos#troubleshooting) |
| Android | [Android SDK](https://docs.bithuman.ai/platforms/android#troubleshooting) |
| Flutter | [Flutter plugin](https://docs.bithuman.ai/platforms/flutter#troubleshooting) |
| Web | [Web embed](https://docs.bithuman.ai/platforms/web#troubleshooting) |
| Python | [Python SDK](https://docs.bithuman.ai/platforms/python#troubleshooting) |
| CLI | [CLI](https://docs.bithuman.ai/platforms/cli#troubleshooting) |
| LiveKit | [LiveKit plugin](https://docs.bithuman.ai/platforms/livekit#troubleshooting) |
| REST API | [REST](https://docs.bithuman.ai/platforms/rest#troubleshooting) · every error code: [Errors](https://docs.bithuman.ai/api/errors) |

## By task

| Task | Its Troubleshooting table |
|---|---|
| Create an avatar | [Create an avatar](https://docs.bithuman.ai/build/create-avatar#troubleshooting) · creation errors: [Agents API](https://docs.bithuman.ai/api/agents#errors) |
| A voice agent | [Voice agent](https://docs.bithuman.ai/build/voice-agent#troubleshooting) |
| A companion app | [Companion app](https://docs.bithuman.ai/build/companion-app#troubleshooting) |
| A kiosk | [Kiosk](https://docs.bithuman.ai/build/kiosk#troubleshooting) |
| A talking video | [Talking video](https://docs.bithuman.ai/build/talking-video#troubleshooting) |
| Persona and gestures | [Persona](https://docs.bithuman.ai/build/persona#troubleshooting) · [Gestures](https://docs.bithuman.ai/build/gestures#troubleshooting) |
| Claude, Cursor and other MCP clients | [MCP server](https://docs.bithuman.ai/build/mcp#troubleshooting) |

## Before you start

- An agent whose status is `ready` ([poll status](https://docs.bithuman.ai/api/agents#poll-status)).

## 1. Connect

| Situation | Expect |
|---|---|
| A session on an agent that has served recently | the avatar appears in a few seconds |
| The first session on a new agent, or at a busy time | up to tens of seconds while capacity starts; later sessions are fast |

If sessions keep failing to connect, check [status.bithuman.ai](https://status.bithuman.ai).

## 2. Idle and speaking

During silence the avatar keeps moving: Expression 2 plays its idle clip and Essence 2 its identity video, both looping smoothly. When speech starts, the lips follow the audio; on Expression 2, the idle motion covers the start of each reply. A running session bills whether the avatar is talking or idle ([pricing](https://docs.bithuman.ai/pricing)); end sessions you are not using.

## Check it worked

The avatar appears, moves while idle, and its lips follow the agent's speech. Frozen frames or motion that looks reversed are faults: report them with the agent code and the time.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| 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_NOT_GENERATED` | the session asked for a model the agent does not have | check `supported_models`; [add the model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent) |
| The session ends at once with `avatar_error: "model_not_generated"` | 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](https://docs.bithuman.ai/platforms/web)) |
| In a room with several agents, the avatar stays silent for one | the avatar follows the agent that called `AvatarSession.start()` | 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 [Agents](https://docs.bithuman.ai/api/agents#errors).

## Next

- [Models](https://docs.bithuman.ai/models) · [Agents API](https://docs.bithuman.ai/api/agents) · [Errors](https://docs.bithuman.ai/api/errors)