Skip to content

Troubleshooting

Common issues and solutions

API Issues

401 Unauthorized

Symptom: API returns 401 error

Causes: - Missing X-API-Key header - Invalid API key - Expired credentials

Solution: 

# Verify API key is set
docker exec vitara-voice-agent printenv | grep API

# Check NGINX is passing headers
docker logs vitara-nginx | grep 401

429 Rate Limited

Symptom: API returns 429 Too Many Requests

Causes: - Exceeding rate limit (100 req/min general, 20 req/min booking)

Solution: - Wait for rate limit window to reset - Implement exponential backoff in client - Contact support if legitimate traffic exceeds limits

503 Service Unavailable

Symptom: API returns 503

Causes: - Voice agent container down - Database connection failure - OSCAR unreachable

Solution: 

# Check container status
docker compose ps

# Check voice agent logs
docker compose logs vitara-voice-agent --tail 50

# Restart services
docker compose restart

Database Issues

Connection Failed

Symptom: "Connection refused" or "ECONNREFUSED"

Causes: - Database container not running - Wrong DATABASE_URL - Port conflict

Solution: 

# Check database is running
docker compose ps vitara-db

# Verify connection
docker exec vitara-db pg_isready -U vitara

# Check logs
docker compose logs vitara-db

Authentication Failed

Symptom: "FATAL: password authentication failed"

Causes: - POSTGRES_PASSWORD mismatch - DATABASE_URL has wrong password

Solution: 

# Check password in .env
grep POSTGRES_PASSWORD .env

# Verify DATABASE_URL uses same password
docker exec vitara-voice-agent printenv | grep DATABASE_URL

Migration Failed

Symptom: Tables don't exist

Solution: 

# Run migrations manually
docker exec vitara-db psql -U vitara -d vitara \
  -f /migrations/001_initial_schema.sql

# Verify tables
docker exec vitara-db psql -U vitara -d vitara -c "\dt"

OSCAR Issues

Connection Timeout

Symptom: OSCAR API calls timeout

Causes: - Network connectivity - OSCAR server down - Firewall blocking

Solution: 

# Test connectivity from container
docker exec vitara-voice-agent wget -O - --timeout=5 http://15.222.50.48:3000/health

# Check OSCAR_API_URL
docker exec vitara-voice-agent printenv | grep OSCAR

OAuth Failed

Symptom: "OAuth signature mismatch" or 401 from OSCAR

Causes: - Invalid consumer key/secret - Invalid token key/secret - Clock skew

Solution: 

# Verify credentials
docker exec vitara-voice-agent printenv | grep OSCAR

# Check server time
date

# Sync time if needed
sudo ntpdate pool.ntp.org

Patient Not Found

Symptom: Patient exists in OSCAR but not found by API

Causes: - Phone number format mismatch - Name spelling differences - Wrong clinic OSCAR instance

Solution: - Verify phone number format (+16045551234) - Check exact name spelling in OSCAR - Confirm correct OSCAR URL in clinic config

Voice Agent Issues

Vapi Not Calling Webhook

Symptom: Voice agent doesn't receive tool calls

Causes: - Wrong webhook URL in Vapi - SSL certificate issues - Firewall blocking

Solution: 1. Verify webhook URL in Vapi dashboard 2. Test endpoint manually: 

curl -X POST https://api.vitaravox.ca:9443/api/vapi/health
3. Check SSL certificate is valid

Call Drops Mid-Conversation

Symptom: Calls disconnect unexpectedly

Causes: - Tool timeout (> 30 seconds) - Vapi max duration exceeded - Network issues

Solution: - Check voice agent logs for slow responses - Verify OSCAR response times - Review Vapi call logs in dashboard

Wrong Language Response

Symptom: Agent responds in wrong language

Causes: - Language detection failure - Transcription error

Solution: - Check Deepgram transcription in Vapi logs - Verify multilingual mode enabled in Vapi - Review system prompt language instructions

SSL Issues

Certificate Expired

Symptom: SSL_ERROR_EXPIRED_CERT_ALERT

Solution: 

# Check expiry
openssl x509 -in /etc/letsencrypt/live/vitaravox.ca/fullchain.pem -noout -dates

# Renew certificate
certbot renew

# Restart NGINX
docker restart vitara-nginx

Certificate Not Trusted

Symptom: SSL_ERROR_UNKNOWN_CA_ALERT

Causes: - Self-signed certificate - Missing intermediate certificates

Solution: 

# Use Let's Encrypt for production
certbot certonly --standalone -d api.vitaravox.ca

# Ensure fullchain.pem includes intermediates
cat /etc/letsencrypt/live/vitaravox.ca/fullchain.pem

Container Issues

Container Won't Start

Symptom: Container exits immediately

Solution: 

# Check logs
docker compose logs vitara-voice-agent

# Common causes:
# - Missing environment variables
# - Port already in use
# - File permission issues

# Check what's using the port
lsof -i :3001

Out of Memory

Symptom: Container killed, OOMKilled in status

Solution: 

# Check memory usage
docker stats --no-stream

# Increase container memory limit in docker-compose.yml
# Or add swap to host

Disk Full

Symptom: No space left on device

Solution: 

# Check disk usage
df -h

# Clean up Docker
docker system prune -a

# Remove old logs
docker compose logs --no-log-prefix > /dev/null

Logs Reference

View All Logs

docker compose logs -f

Filter by Time

docker compose logs --since "1h" vitara-voice-agent

Search Logs

docker compose logs vitara-voice-agent 2>&1 | grep -i error

Log Locations

Service Location
Voice Agent stdout (Docker)
NGINX /var/log/nginx/ in container
PostgreSQL stdout (Docker)

Health Checks

Quick Health Check

curl -s https://api.vitaravox.ca:9443/health | jq

Comprehensive Check

# All containers
docker compose ps

# Database
docker exec vitara-db pg_isready -U vitara

# Voice agent
curl -s http://localhost:3001/health

# NGINX
curl -s http://localhost:9080/health

# OSCAR
curl -s http://15.222.50.48:3000/health

Getting Help

If issues persist:

  1. Check documentation: vitdocs.vitaravox.ca
  2. Review logs: docker compose logs -f
  3. Contact support: support@vitaravox.com

Include in support request: - Error messages - Relevant logs - Steps to reproduce - Environment (production/development)