Docs Troubleshooting

Troubleshooting

Read the error code first, then check the browser, the server, and the agent configuration.

Error codes

The controller publishes a human-readable error and a stable errorCode. Branch on the code, show the message, and use the table below to find the likely cause.

ConversationErrorCode
Code	Likely cause	What to check
`not-supported`	Missing browser API, text only misuse, or a destroyed controller.	Check `AudioManager.isSupported()` and whether the target is a voice session.
`insecure-context`	The page is not on HTTPS or localhost.	Serve the app from a secure origin.
`permission-denied`	The user or browser blocked the microphone.	Check site permissions and any iframe `allow` policy.
`audio-failed`	The audio graph could not be created or read.	Check Web Audio support, output devices, and the console.
`invalid-target`	The target is not an agent id or a supported conversation URL.	Use an `agent_` or `seng_` id, or a full WebSocket URL.
`signed-url-failed`	The server route failed, timed out, or returned an unexpected payload.	Check the route, the server key, and the network response.
`connection-failed`	The socket could not open or the handshake failed.	Check the network, agent id, signed URL, and browser console.
`connection-timeout`	No metadata arrived within 15 seconds.	Check the agent configuration and whether the network blocks WebSocket upgrades.
`server-closed`	The server closed the socket or the wait queue expired.	Read the close reason, then retry or check agent capacity.
`protocol-error`	An event, approval result, or negotiated format did not match expectations.	Enable `debug` and inspect the event type.
`device-not-found`	The selected device disappeared.	Refresh `listAudioDevices()` and fall back to the default.
`device-busy`	Another app holds the microphone.	Close the other app or choose a different input.
`device-constraints`	The requested device cannot satisfy the audio constraints.	Use the default device or relax the constraints.
`device-switch-failed`	A live input or output switch failed.	The previous device is restored. Check whether output routing is supported.

Microphone

Confirm the page uses https:// or http://localhost. Other origins cannot call getUserMedia.
Check the browser site settings. A denied permission does not prompt a second time until the site is reset.
If the page is embedded, make sure the iframe allows microphone access with the right allow attribute and a compatible Permissions Policy.
Start the session from a click or tap. Starting during module evaluation or automatically after load can be blocked or suspended.

Input device labels are often empty before permission is granted. Call listAudioDevices() after the first successful session if you need labels.

Connection

Work from the innermost failure outward:

invalid-target: public ids start with agent_ or seng_. A full URL can use ws:// or wss://, and http:// or https:// URLs are normalized to the matching WebSocket scheme.
signed-url-failed: open the route directly in the browser with the same agent id. A missing ELEVENLABS_API_KEY returns HTTP 500. A rejected key returns a 502 with a message about the workspace. A 404 means the agent was not found.
connection-failed: check the browser network panel for the WebSocket upgrade. Proxies and content security policies can block wss://.
connection-timeout: the socket opened but no metadata arrived in 15 seconds. Check that the agent exists and is not paused.
queueStatus === 'waiting': the agent is at its concurrency limit. The UI can show the wait state. A timed_out state also publishes server-closed.

A public id connects to the US origin by default. Set serverLocation to eu-residency or in-residency when the agent lives elsewhere, or pass an explicit origin.

Audio

Common audio symptoms
Symptom	Check
No microphone input	Permission, `isMuted`, the selected input device, and whether the session is voice or text only.
No agent sound	Browser tab mute, system output, `outputGain`, the selected output device, and whether playback was flushed by barge-in.
Choppy playback	Main-thread work, a suspended audio context, and very small `inputChunkDurationMs` values.
Agent interrupts itself	Lower `vadThreshold` sensitivity by raising the value, or set `interruptOnUserSpeech: false`.
No output device list	Some browsers expose only the default device, or hide labels until microphone permission is granted.

The controller does not retry a failed media operation silently. Every switch returns a boolean and sets error when it cannot complete.

Static hosting

GitHub Pages has no server runtime, so /api/signed-url does not exist there. The showcase builds with PUBLIC_HOSTING_MODE=static, hides signed mode, and uses public agent ids. If you deploy the app yourself, either provide a real server or keep signed mode out of the static build.

For a project site, set PAGES_BASE_PATH to the repository path, for example /svelte-elevenlabs. Without it, links and assets may resolve from the domain root and return 404.

Svelte lifecycle

useConversation outside initialisation: call it synchronously in a component script. In a store, test, or async function, use createConversation.
Context missing: getConversationContext and useConversationClientTool require a ConversationProvider ancestor.
Leaked sessions in tests: call destroy() when a manually created controller is no longer needed. It is idempotent.
SSR surprises: importing the package is safe, but starting a session during SSR is not. Start from a browser event and read browser APIs only after mount.

Diagnostics

Turn on structured logging for one session:

const conversation = useConversation({  agentId: 'agent_your_public_id',  debug: true,  onDebug: (event) => console.log(event.kind, event.message, event.data),  onIncomingEvent: (event) => console.log('in', event.type),  onOutgoingEvent: (event) => console.log('out', event.type)});

The debug stream omits transcript text and credentials. The raw event callbacks do include protocol payloads, so remove them before shipping or route them to a safe development logger.

Still stuck

Open an issue at GitHub issues with the package version, browser and version, the exact error code, whether the session used a public id or a signed URL, and the smallest reproduction you can share. Do not include the API key or a live signed URL.

For protocol details beyond this package, use the ElevenLabs Conversational AI documentation.

Edit this page on GitHub