Skip to main content
Every failure here is quiet. A mismatched agent name mints a valid token, opens a real room, connects the browser, and logs no error anywhere. So read this page before you read logs.

​
Run the doctor first

It prints one line per check with the fix underneath. Without --live it reads configuration only. With --live it also probes the three provider APIs, asks docker compose ps whether all four services are running, hits the backend’s /health, mints a real token, and reads /api/v1/agents. Two things about how it reads config:
  • It runs through the agent’s environment because it imports httpx. Hence cd agent and the ../ in the path.
  • It parses the root .env only. A key that lives in agent/.env and nowhere else is invisible to it, and it will report that key as unset.

​
The room opens and nothing ever speaks

AGENT_NAME and VITE_AGENT_NAME differ. LiveKit dispatches the worker by exact string match. When the two differ the token is valid, the room is real, the browser connects, and no worker is ever dispatched. Nothing errors. The doctor checks this before anything else for that reason.
Byte-identical, in the root .env. Change both or neither.

​
You changed a VITE_ value and nothing changed

VITE_TOKEN_ENDPOINT, VITE_AGENT_NAME and VITE_API_BASE_URL are build arguments in docker-compose.yml. They are baked into the frontend bundle when the image is built.
A plain docker compose restart keeps the old value silently, which is one of the ways you end up with a mismatched agent name.

​
Compose works but the manual run does not, or the reverse

You edited the wrong .env. docker compose reads the root one and nothing else. The per-service files (agent/.env, backend/.env, frontend/.env) are for running that service by hand.

​
The browser says “invalid API key”

LIVEKIT_URL is unset or is still wss://your-project.livekit.cloud. The message points at the key, but the URL is the problem. The doctor names this case explicitly so you do not rotate a key that was never wrong.

​
Saving the prompt in the console is refused

Two different refusals, and the status code tells them apart.
  • 403. CONSOLE_WRITES_ENABLED is off. It defaults to false in code and compose sets it to true. The editor loads read-only and says why.
  • 409. The backend has no read-write mount of ./agent/prompts, so the save cannot land. The message names the path it could not write, and the prompt the agent is running is unchanged.
See Persona.

​
Console edits to the LiveKit project do not reach the worker

The worker takes its LiveKit project from the backend when BACKEND_API_URL and BACKEND_API_TOKEN are both set, and restarts itself when the stored project changes. Two failures:
  • AGENT_SERVICE_TOKEN and BACKEND_API_TOKEN differ. They are one secret with two names. The backend answers 403 and the worker logs that it was refused.
  • Both are empty. The endpoint that serves the credentials is disabled rather than opened, and the worker stays on its own environment.
Generate one value and put it in both:

​
The Calls page is empty after a real call

Call reporting needs BACKEND_REPORTING_ENABLED=true and the matching service token above. Compose turns reporting on by default, but without the token pair nothing is sent. Console mode never reports, whatever the flag says.

​
The worker exits immediately and names a LiveKit value

It needs all three of LIVEKIT_URL, LIVEKIT_API_KEY and LIVEKIT_API_SECRET. Rather than looping raw 401s under restart: unless-stopped, it refuses to start and says which one is missing. The doctor reports each of the three separately.