> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talking-avatar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for common problems with Realistic Avatars, Voice Agents and your account.

For problems with the 3D avatar, see [Open Source troubleshooting](https://docs.talking-avatar.dev/open-source/troubleshooting.md).

## Realistic Avatars

> **LiveAvatar.start rejects with code 4001**
>
> The API key is invalid, revoked or missing. Check that `TALKING_AVATAR_API_KEY` is set on the server, has no extra spaces or quotes, and still appears on the dashboard's **API keys** page. Create a new key if you lost it: keys are shown only once.

> **Sessions end, or won't start, with code 4002**
>
> Your balance is below one minute (\$0.02), it ran out during the session, or you reached your monthly spending limit. Add credits on **Billing**, turn on auto top-up, or raise the limit.

> **A session ended with code 4003**
>
> Sessions can run for up to 3 hours. Start a new session to continue.

> **No WebSocket in this runtime**
>
> Node.js 18 and 20 have no global `WebSocket`. Upgrade to Node.js 22, or install `ws` and pass it in:
>
> ```js theme={null}
> import WebSocket from "ws";
> const avatar = await LiveAvatar.start({ apiKey, avatar: "ava4", WebSocket });
> ```

> **The avatar shows but there's no sound**
>
> Browsers block sound until the user interacts with the page. Call `view.connect()` from a click. If the status is `muted`, show a button that calls `view.unmute()`.

> **The voice is heard twice**
>
> Your app still plays the agent's audio somewhere else (an `<audio>` element, a speaker stream, or `track.attach()` in LiveKit). The avatar plays the voice itself; remove the other playback.

> **The voice sounds too fast, too slow, or like noise**
>
> The `sampleRate` doesn't match your audio, or the audio isn't raw PCM16 mono. Ask your TTS for raw PCM, pass its exact sample rate, and decode MP3, Opus or WAV (and strip WAV headers) first. See [Stream audio](https://docs.talking-avatar.dev/realistic-avatars/streaming-audio.md).

> **The page never connects**
>
> * Check that your `/avatar` route returns `avatar.handleView(req.body)` as JSON, and parses JSON bodies.
> * Check that the `LiveAvatar` for that conversation is still running (not closed).
> * Users behind strict firewalls may need a TURN server: pass it in `iceServers`.

> **handleView throws 'handleView is for direct output'**
>
> You started the session with the `livekit` option. In LiveKit mode, the avatar joins your room and your LiveKit client plays it: you don't need `handleView` or `LiveAvatarView`.

## Voice Agents

> **Callers see 'This agent can't take calls right now'**
>
> The agent's account can't start calls. Check your balance (at least \$0.02 is needed) and your monthly spending limit on **Billing**. Callers aren't told why.

> **Callers see 'This agent isn't available'**
>
> The agent is turned off (**Share & embed** → **Taking calls**), deleted, or private and opened without a valid link.

> **The Test call button is disabled**
>
> Create the agent first, and make sure **Taking calls** is on. Test calls use the last saved version.

> **Callers see 'Microphone needed'**
>
> The browser blocked the microphone. They should allow it in the browser's site settings and try again. In an iframe, the embed code must include `allow="microphone; autoplay"`.

> **Callers see 'Call limit reached'**
>
> That caller has started many calls to the same agent recently. They can try again later. This protects your balance from abuse.

> **The agent says '\[Company]' or other placeholders**
>
> The prompt still has `[placeholders]`. The **Agent** tab shows how many are left to fill in.

> **The agent cuts callers off, or waits too long**
>
> Adjust [turn-taking](https://docs.talking-avatar.dev/voice-agents/conversation-settings.md#turn-taking): with **Semantic**, choose **Patient** to give callers more time, or **Eager** for faster replies. With **Voice activity**, raise **Silence** to wait longer.

> **A tool isn't called, or fails**
>
> * Make the tool's **When to use it** description specific, and mention the tool in the prompt.
> * Your endpoint must be HTTPS, answer `POST` with JSON within 10 seconds, and return a `2xx` status.
> * The **Calls** tab shows how many tool calls each call made; your server's logs show what it received.

> **The webhook shows 'Couldn't reach it' or 'Failed'**
>
> Your endpoint didn't answer with a `2xx` within 10 seconds. Check that it's public HTTPS, accepts `POST` JSON, and that signature checks use the raw body and the right secret. We don't retry; the call and its transcript are still in the dashboard.

> **Signature verification fails**
>
> Verify against the raw request body (before JSON parsing), use the agent's own secret (each agent has one), and update your servers after **Rotate secret**. See [Verify signatures](https://docs.talking-avatar.dev/api-reference/verify-signatures.md).

> **The share page shows 'This link has expired'**
>
> The [private link](https://docs.talking-avatar.dev/voice-agents/private-agents.md) is past its expiry, or has started its maximum number of calls (*This link has no calls left*). Make a new link.

## Account and billing

> **I didn't get a sign-in code**
>
> Check spam, and that you typed your email correctly. Then complete the security check and click **Send a new code**. You can request up to 5 codes in 10 minutes.

> **'No account found for this email'**
>
> There's no account for that email yet. [Create one](https://app.talking-avatar.dev/sign-up), or sign in with Google if that's how you signed up.

> **My credits haven't arrived after paying**
>
> Credits are added a few seconds after payment, and the **Billing** page refreshes itself. If they still haven't arrived after a few minutes, email [support@talking-avatar.dev](mailto:support@talking-avatar.dev) with your receipt.

> **Auto top-up didn't charge**
>
> Auto top-up needs a saved card. When you first enable it, click **Save & add card** and finish the checkout. If your card is declined or the saved card is removed, add it again the same way.

Still stuck? See [Support](https://docs.talking-avatar.dev/help/support.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.