Troubleshooting

Server

Port already in use

Symptom: EADDRINUSE: address already in use :::3100

Fix: Kill the existing process or change PORT in .env.

Invalid configuration

Symptom: Invalid configuration: followed by validation errors.

Fix: Check .env.example for correct format.

MCP Connection

SSE connection fails

Symptom: Client can't connect to /sse.

Fix: Verify the server is running: curl http://localhost:3100/health

Tool calls return auth errors

Symptom: Missing or invalid security token

Fix: In demo mode, set DEMO_MODE=true. In production, pass token via SSE.

Webhooks

Inbound messages not arriving

Fix:

  1. Expose server publicly: ngrok http 3100
  2. Set WEBHOOK_BASE_URL to your ngrok URL
  3. Run comms_provision_channels to configure Twilio webhooks

Signature verification failed

Symptom: 403 Forbidden on webhook endpoints.

Fix: Ensure TWILIO_AUTH_TOKEN matches your Twilio account and WEBHOOK_BASE_URL matches the URL Twilio is hitting.

Replay detected

Symptom: 403 Replay detected

Fix: Working as intended. The nonce cache prevents duplicate webhook processing.

Voice Calls

Call connects but no AI response

Fix: Ensure agent is connected to /sse?token=. Falls back to answering machine after 8 seconds.

ConversationRelay WebSocket errors

Fix: Ensure WEBHOOK_BASE_URL is publicly accessible via HTTPS. Twilio requires WSS.

Rate Limiting

HTTP 429

Fix: Default is 60/min per IP. Increase via HTTP_RATE_LIMIT_PER_IP or wait.

Tool call rate limit

Fix: Use comms_set_agent_limits to increase limits, or wait for reset.

Compliance

Content filter block

Fix: Rephrase the message. The filter blocks threats and profanity.

TCPA block

Fix: Wait until allowed hours (8 AM – 9 PM local time).

DNC block

Fix: Remove from DNC list in the database if incorrect.

Database

Table not found

Fix: Server runs migrations on startup. Ensure it has started at least once.

Database locked

Fix: Ensure only one server instance is running. For production, use Postgres.

Admin UI

Setup page blank

Fix: Check browser console. The page uses inline JS/CSS requiring relaxed CSP.

Admin API returns 401

Fix: Include Authorization: Bearer header.

Demo Mode

Tests fail

Fix: Set DEMO_MODE=true in .env and restart before running tests.

← Home