Troubleshooting

401 on the upgrade

The HMAC handshake failed. Causes:

• Secret mismatch - BRIDGE_SECRET does not equal the value StandIn holds from pairing. They must match exactly.
• Clock skew - the timestamp is outside the freshness window (HMAC_FRESHNESS_MS, default 60 s). Sync the clocks (NTP).
• Replayed handshake - the same (callId, ts, sig) tuple was already used. This is the single-use guard doing its job; a genuine retry uses a fresh timestamp.
• Secret unset - the bridge fails closed if BRIDGE_SECRET is empty; every upgrade is rejected.

409 Conflict

A live session already owns that call id (a retry or rollout reconnect). The bridge rejects the duplicate so it does not open a second billed ElevenLabs conversation for one call. It clears when the first session tears down.

503 Service Unavailable

A connection cap was hit: MAX_CONNECTIONS (default 64) or MAX_CONNECTIONS_PER_IP (default 8). Raise them for a busier deployment, or check for a client that is not closing sockets.

Call connects, then agent-unavailable

The bridge could not open the ElevenLabs conversation. Check ELEVENLABS_AGENT_ID, that ELEVENLABS_API_KEY has access to that agent, and that the signed-URL mint succeeded (private agents). The bridge mints the signed URL per call and retries once on failure.

No audio, or garbled audio, and the call ends

The agent’s audio format is not pcm_16000. Set both the input and output format to PCM 16000 Hz in the agent’s voice settings. The bridge validates this at call start and now ends the call on a mismatch rather than running a whole call with dead or garbled audio - so this shows up as an immediate teardown with a clear log line.

Governor never fires

MAX_CALL_MINUTES must be a number. A non-numeric value stops startup with a clear error (numeric env vars fail loud), so if the process started, the value parsed. Confirm it is greater than 0 (0 disables the governor).

The agent is silent in a meeting (but fine 1:1)

That is the group-call gate. In a call the worker reports as having two or more humans, the agent’s reply audio is withheld until someone says one of GROUP_CALL_WAKE_PHRASES (default assistant), then flows for GROUP_CALL_FOLLOW_UP_WINDOW_MS (default 12 s). Say its name, rename the wake phrase to whatever people actually call it, or set GROUP_CALL_REQUIRE_ADDRESS=false to turn the gate off. A 1:1 call is never gated. Note that GROUP_CALL_FOLLOW_UP_WINDOW_MS=0 also disables the gate here rather than requiring every turn to name the agent - the bridge gates at the audio egress, where the window is the only thing that can open the gate.

Its opening line is subject to the same gate. If the roster arrives before the agent starts speaking, the greeting is withheld too.

Ambient vision is on but the agent never mentions the screen

Check the log at call start. One of these is there:

• ambient vision on: ... - it is running. If nothing arrives, confirm StandIn is actually sending video.frame (the caller must be sharing), and that recording is active unless you set AMBIENT_VISION_REQUIRE_RECORDING=false.
• ambient vision is enabled but no vision describer is configured - set VISION_API_URL + VISION_MODEL, or pass a VisionDescriber to startServer. A description is the only route that does not make the agent start talking, so without one the feature has nothing to do.
• nothing at all - AMBIENT_VISION_ENABLED is false (the default), or MAX_VISION_PER_MINUTE=0, which means off rather than unlimited.

An unchanged screen is skipped on purpose, so a static slide is described once, not every six seconds.

Call ends with no-answer

The stale-call reaper. The worker connected and sent session.start, but the ElevenLabs conversation never opened within STALE_CALL_REAPER_SECONDS (default 120), so the bridge stopped holding the call id and the connection slot. Look for the preceding ElevenLabs connect error; 0 disables the reaper if you would rather let such calls sit.

Startup error about EL_HOST

EL_HOST is restricted to *.elevenlabs.io so the API key can only be sent to ElevenLabs. Use one of the documented regional hosts, or set EL_HOST_ALLOW_ANY=true for a proxy you control.

Port already in use

The CLI prints a friendly hint on EADDRINUSE. Set PORT to a free port.

Where the logs are

The bridge logs one line per event to stdout/stderr, scoped by call id. Set LOG_LEVEL=debug for the verbose relay detail (an invalid value falls back to info). Transcript logging additionally requires LOG_TRANSCRIPTS=true and Teams recording to be active.