https://livekit.io logo
Join Slack
Powered by
How do I debug why dispatch routing error
# ask-ai
j
How do I debug why dispatch routing error
t
Thanks for reaching out, David. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.
j
image.png
t
Thanks — I can help debug your dispatch routing error. To target the right steps, could you tell me: • Is this SIP-triggered (inbound call) or API/participant-token triggered? • The exact error message or observable symptom (room not created, agent not joining, HTTP 4xx/5xx, logs showing "no dispatch", etc.). • Agent SDK and language (Python/Node.js) and agent server version. • Whether you use explicit 
agent_name
dispatching or automatic dispatch. • Any relevant config snippets or commands (dispatch rule JSON, 
RoomConfiguration
snippet, or 
lk
CLI commands and outputs). • Whether this was working previously or is a new setup. If you prefer, paste the agent name you expect to be dispatched and a short copy of the dispatch rule or trunk mapping — I’ll review for common mismatches (agent name mismatch, missing 
RoomAgentDispatch
in 
RoomConfiguration
, trunk not linked to rule, or JWT permission issues). Sources: Agent dispatch | LiveKit docs | Accepting calls overview | LiveKit docs | Agents telephony integration | LiveKit docs | Agent server options | LiveKit docs | sip | livekit/livekit_composite | DeepWiki
Thanks — I see you’re asking how to debug a dispatch routing error and you attached a dashboard screenshot showing 3 “Agent dispatch errors” and 0 active sessions for Dec 28 → Dec 29. I’ll walk through the most likely causes and targeted checks, then ask a couple quick questions so I can narrow things down. Quick checklist to debug dispatch routing errors 1. Confirm dispatch trigger • Is the dispatch SIP-triggered or API/participant-token triggered? (This changes which resources to inspect.) 1. Verify agent configuration • Ensure your agent is configured for explicit dispatch if you set an 
agent_name
. If 
agent_name
is present, automatic dispatch is disabled and you must explicitly dispatch that agent. • Confirm the 
agent_name
in your agent code exactly matches the name used in the dispatch rule or request (case-sensitive). 1. Check room/agent registration • Verify the RoomConfiguration includes the 
RoomAgentDispatch
entry with correct 
agent_name
and any required metadata. • If using participant tokens, confirm tokens include the room dispatch configuration. 1. Inspect SIP trunk & dispatch rule (if SIP) • Ensure the inbound trunk is configured for the called number. • Confirm the dispatch rule references the correct 
trunk_ids
and includes a 
room_config
that lists your agent by name. 1. Use CLI and logs • Run these to list and inspect rules/resources: ◦ 
lk sip dispatch list
◦ 
lk sip inbound list
◦ 
lk dispatch list --room <room-name>
• Enable debug logging for the agent and check deployment logs: ◦ Start agent with debug log level (example): 
uv run agent.py start --log-level=DEBUG
◦ View agent deploy logs: 
lk agent logs --log-type=deploy --id=<agent-id>
1. Look for common failure points • Mismatched or missing 
agent_name
• Dispatch rule pointing to wrong trunk or missing trunk • Room not created because token/JWT lacks required permissions • Agent fails to join due to runtime errors — check agent process logs for join failures or exceptions What I need from you to narrow this down • Is this SIP-triggered or API/participant-token triggered dispatch? • Exact error text or logs (agent logs, dispatch service logs, or any error codes you see). • Agent SDK and language (Python/Node) and agent version. • Example of the dispatch rule or RoomConfiguration (redact secrets). • Whether this was working previously or this is a new setup. If you share those details (especially the error messages and whether SIP is involved), I’ll give the exact commands and log locations to pull and interpret, plus immediate next steps to fix the root cause.
j
Where are the logs
This is cloud
t
Thanks — since this is LiveKit Cloud, here’s where to find logs for dispatch routing issues and what to check. Agent runtime & deploy logs (CLI) • Stream agent runtime logs: 
lk agent logs
• Deployment/build logs only: 
lk agent logs --log-type=deploy
Use these to see agent start errors, join failures, or exceptions when handling a dispatch. LiveKit Cloud Dashboard (Agent observability) • Open your project → Agent insights (or Agent observability) to view per-session traces, transcripts, and logs. Use this to correlate a dispatch event to room creation, agent join time, and any session-level errors. SIP / dispatch configuration checks • List dispatch rules and inbound trunks with the CLI/SDK to confirm the rule/trunk mapping: ◦ CLI: 
lk sip dispatch list
and 
lk sip inbound list
◦ SDK: 
sip.list_sip_dispatch_rule(...)
/ 
sip.list_sip_inbound_trunk(...)
Check that the dispatch rule references the correct 
trunk_id
and 
room_config
(agent_name/room_prefix). Room & participant events • Inspect room creation and participant join events via Agent insights or agent logs to confirm whether a room was created and whether a SIP participant or agent joined. What to share if you want me to look closer • Whether the dispatch was SIP-triggered or API/token-triggered. • A snippet of the error from 
lk agent logs
or the Agent insights session logs (redact secrets). • The dispatch rule or RoomConfiguration (redact secrets) and the agent name used. Tell me which project and agent ID (or paste the exact log lines/error) and I’ll point to the exact log entries and next steps. Sources: Deploying to production | LiveKit Docs | sip | livekit/livekit_composite | DeepWiki | Streamline Troubleshooting with Agent Observability
j
I want through admin ui
t
Got it — you want to find logs in the LiveKit Cloud Admin UI. Here’s where to look and what to inspect. 1) Open the LiveKit Cloud Dashboard • Sign into the LiveKit Cloud admin console and select the correct project. 2) Go to Agent insights / Agent observability • Navigate to the “Agent insights” (or “Agent observability”) tab for your project. • This view shows per-session traces, transcripts, and logs tied to agent sessions and dispatch events. 3) Find the dispatch timeframe or session • Use the time picker to match the window from your screenshot (Dec 28, 4:00 PM → Dec 29, 12:00 AM). • Filter by agent name, room prefix, or session ID if you have them. 4) Inspect the session details • Click the session/row that matches the dispatch time. Inside you’ll see: ◦ Session timeline / traces showing when dispatch was attempted, room created, and agent join attempts. ◦ Per-session logs and any error messages or stack traces. ◦ Participant list (to confirm whether SIP participant or agent joined). ◦ Transcripts/metadata (if enabled) for extra context. 5) Review related dashboards/metrics • Open the metrics panels (charts) showing “Agent dispatch errors” and “Active sessions” for the same timeframe to correlate spikes with specific sessions. • Hover the chart points to jump directly to associated session(s). 6) If SIP-related, confirm dispatch rule info • In the dashboard, find the SIP/telephony or Dispatch configuration area (may be under “Integrations” or “SIP”). • Verify the inbound trunk, called number, and dispatch rule mappings (room_prefix and 
agent_name
) shown there. If you want, tell me: • The project name and agent name (or a session ID/time), and I’ll point to the exact session entries to inspect. • Or paste a specific session log line or error you see in the UI and I’ll explain what it indicates and next steps.
m
@jolly-autumn-53818 I'll DM you
2 Views
Open in Slack
PreviousNext
Powered by