Skip to content

Troubleshooting

Find the symptom, check the cause, apply the fix. If no row fits, read the session back.

SymptomUsual causeFix
connect throws a TypeError that does not mention headersThe connect response’s headers is a plain object, and the transport needs a Headers instance.Add the one line in Connect your app, and call connect rather than startBotAndConnect.
403 origin_not_allowedThe page’s origin is not in the pk_ key’s allowed origins, or the request has no Origin at all (a server or a native app).Add the origin with update_api_key_origins, or start the session from your server with an sk_. See Keys and authentication.
401The key is wrong, revoked, or for another agent.Check last_used_at in list_api_keys. See Keys and authentication.
409 agent_not_configuredThe agent has no brain_url and no Cortex credentials.Set a brain_url, or call create_agent_credentials. See Deploy the brain.
409 agent_archivedThe agent is archived.unarchive_agent.
400 invalid_config, details.code unsupported_language or unsupported_voiceThe recognizer does not hear stt.language, the voice is not served, or the voice does not speak tts.language.Pick values from the catalog.
400 recording_not_permittedA pk_ sent record: true.Send it from your server, or set the agent’s default. See Recordings.
sessions_created is far above sessions_startedThe page mints on load, an origin is refused, or connect throws before the transport starts.See the gap that means a broken embed.
SymptomUsual causeFix
The user hears “Sorry, I’m having trouble connecting right now”, then the session endsVoqalize could not reach your brain for 10 seconds: the service is down, the brain_url is wrong, TLS fails, or the handshake answers 401 or 403. end_reason is brain_unreachable.Check the route and the token. See Deploy the brain and what your user hears.
The session ends at once, with end_reason brain_disconnectedYour brain closed the socket, often with 4000 after the token failed verification.See the brain-connection token.
The user hears “Sorry — that’s taking longer than I expected.”A turn produced no speech within 15 seconds, or the time the brain set in Config.late: the model called a tool and said nothing, or a callback raised.Say the line in the same response as the tool call (Tools); check your brain’s logs for the exception.
The greeting plays, then no turn ever speaks, with brain: turn failed and a TypeError in your logsA tool is a plain def.Make every tool async def. See Tools.
on_user_idle never firesIdle detection is off by default.Set idle.timeout_ms. See Voice and language.
SymptomUsual causeFix
It refers to things the user never heardHistory records what the brain generated, not what was heard.Record fin.heard from on_finalize. See Transcripts and heard truth.
The user hears two acknowledgementsVoqalize’s acknowledgement is on, and your brain opens with its own.Turn ack off, or drop your own opener. See Speaking.
Right words, wrong accentOnly one language leg was changed, or tts.language was never set.Set both legs every time. See Voice and language.
A configure raises RequestRejectedThe voice does not speak that language, or the recognizer does not hear it.Read code and detail. See Error codes.

The screen does not do what the agent says

Section titled “The screen does not do what the agent says”
SymptomUsual causeFix
The brain’s reply was never heard and the screen did not moveThe user talked over the turn before your code reached dispatch, so the turn was cancelled (never_spoken units in the call record). An action already dispatched still arrives.Expected barge-in behaviour. Dispatch next to the sentence it belongs with. See Reading a call back.
An action never reaches the page’s handlerThe action class was renamed, so the page listens for the old name.Rename both sides together. See Actions.
Actions go missing under load, with an overload errorYour SDK shed frames from a full queue.See overload.
Speech and screen disagree on a Stage siteA cue was dropped or a move failed.Run the stage-debug skill. See Stage.

Take the session_id from your connect response or your brain’s logs, and on the MCP server:

  1. get_call_record: what was said and heard, turn by turn. Check record is found before concluding the session was silent.
  2. get_session_logs: Voqalize’s lines, for why.
  3. get_session_events: how far the session got, even while it runs.

Reading a call back explains each. If you still need us, send the session_id, or the correlation_id from a refused request.