Skip to main content

Knowledge > Runbooks > Voice Ops > Debug a Voice Call Issue

Debug a Voice Call Issue

Diagnose and fix problems with voice calls — wrong responses, tools not working, routing failures, or audio issues. All debugging targets the live production system.

Prerequisites​

  • Supabase MCP or direct DB access
  • Access to Railway dashboard (for logs and environment variables)
  • Access to LiveKit Cloud dashboard (cwa-voice-9x077mph project) for SIP/room status
  • Phone number or church UUID of the affected church

Steps​

  1. Pull the recent call log for the affected church

    SELECT id, church_id, created_at, ended_at,
           call_outcome, duration_seconds, transcript, error_message
    FROM voice_call_logs
    WHERE church_id = '[uuid]'
    ORDER BY created_at DESC
    LIMIT 5;

    If you have the caller's number instead of a church UUID, search by caller_number field.

  2. Review the transcript for the failing call. Look for:

    • Where the agent gave an incorrect response
    • Tool call attempts and their results
    • Utterances that were filtered/ignored
    • Any [SYSTEM] or error annotations in the transcript

  3. Verify the call routed to the correct church

    SELECT cva.church_id, cva.twilio_phone_number, cva.is_active, c.name
    FROM church_voice_agents cva
    JOIN churches c ON c.id = cva.church_id
    WHERE cva.twilio_phone_number = '+1[10-digit-number]';

    If the number maps to the wrong church, update church_voice_agents.twilio_phone_number.

  4. Check is_active status

    SELECT is_active, agent_name, greeting_message
    FROM church_voice_agents
    WHERE church_id = '[uuid]';

    If is_active = false, the agent will not answer. Set to true if the subscription is active.

  5. Check session caching — session.py caches church config for 5 minutes. If you just updated the DB config, wait 5 minutes then test again, or trigger a fresh session.

  6. Verify environment variables are set in Railway

    All API keys for the voice agent are set in Railway (NOT in Vercel env vars). Check the Railway service environment for:

    • LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET
    • DEEPGRAM_API_KEY (STT)
    • CARTESIA_API_KEY (TTS)
    • GEMINI_API_KEY (Coordinator LLM + classification)
    • ANTHROPIC_API_KEY (Care Agent LLM)
    • SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY

    An expired or missing GEMINI_API_KEY causes the Coordinator agent to fail silently. Missing LiveKit variables cause the worker to fail at startup.

  7. If tools are failing (prayer requests not saving, callbacks not creating):

    -- Test that the service role can insert into shared tables
    SELECT COUNT(*) FROM voice_prayer_requests WHERE church_id = '[uuid]';
    SELECT COUNT(*) FROM voice_callback_requests WHERE church_id = '[uuid]';

    If you get an RLS error, check that SUPABASE_SERVICE_ROLE_KEY is set in the voice agent environment.

  8. Check turn_processor.py filtering

    If callers report that the agent isn't responding to their words, the utterance may be filtered by noise detection. Review turn_processor.py noise thresholds. Transcripts labeled [FILTERED] confirm this.

  9. Check voice_call_logs.error_message for any Python exceptions or Cartesia SDK errors.

  10. If a code bug is confirmed, fix the code and redeploy:

    # Push to main — Railway auto-deploys the Python service
    git push origin main
    # Wait ~2 minutes for Railway to build. LiveKit Cloud connects automatically.

Known Issues​

  • 5-min session cache — config changes to church_voice_agents take up to 5 minutes to apply to live calls.
  • Railway cold start — if the Railway service restarts after a period of inactivity, the first call may take a few extra seconds to connect while the worker reconnects to LiveKit Cloud.
  • LiveKit Cloud SIP gateway — if calls are failing without reaching the agent at all (no voice_call_logs rows), check the LiveKit Cloud dashboard for SIP dispatch rule configuration and ensure the Twilio SIP trunk URL is correct.

Verification​

Place a test call to the affected number and confirm the issue is resolved. Check voice_call_logs for a new successful call entry.

See Also​