Troubleshooting

​

”No voicegw.yaml found”

1. ./voicegw.yaml (current working directory)
2. ~/.config/voicegateway/voicegw.yaml
3. /etc/voicegateway/voicegw.yaml

voicegw init

export VOICEGW_CONFIG=/path/to/voicegw.yaml
voicegw serve

​

“Provider not configured”

1. Check spelling. Provider names are lowercase: openai, deepgram, anthropic, etc.
2. Ensure the provider is in your config file:
   providers:
     openai:
       api_key: ${OPENAI_API_KEY}
   
3. VoiceGateway meters native provider/model instances by model_id and does not need the provider wheel installed itself. Install the plugin your agent uses in your own agent, for example pip install livekit-plugins-openai

​

”Budget exceeded”

• Increase the budget in voicegw.yaml:
  projects:
    my-app:
      daily_budget: 50.00
  
• Switch to warn mode to log warnings instead of blocking:
  projects:
    my-app:
      budget_action: warn
  
• Check the dashboard at http://localhost:8080 (the daemon’s serve port) to see where costs are accumulating
• Budgets reset daily at midnight UTC

​

”Connection refused localhost:11434”

1. Start Ollama:
   ollama serve
   
2. Verify it is running:
   curl http://localhost:11434/api/tags
   
3. If Ollama is on a different host or port, update your config:
   providers:
     ollama:
       base_url: http://your-host:11434
   
4. If using Docker Compose with the local profile:
   docker compose --profile local up -d
   
   The Ollama container needs time to download models on first start.

​

”Failed to decrypt” / Cryptography errors

1. VoiceGateway uses the cryptography package for key encryption. If you rotated or lost the encryption key, re-set your API keys in voicegw.yaml using plain ${ENV_VAR} references
2. Ensure cryptography>=43.0 is installed:
   pip install --upgrade cryptography
   
3. If using encrypted storage, check that the VOICEGW_SECRET environment variable is set to the same value used when keys were stored. (See src/voicegateway/core/crypto.py for the canonical secret-resolution order: env var, then ~/.config/voicegateway/.secret, then auto-generated.)

​

Docker dashboard crashes on startup

1. Check logs:
   docker compose logs dashboard
   
2. Ensure the config file is mounted in your docker-compose.yml:
   services:
     voicegateway:
       volumes:
         - ./voicegw.yaml:/app/voicegw.yaml:ro
   
   Then restart:
   docker compose up -d
   
3. Check port availability (default: 8080, the daemon’s serve port):
   lsof -i :8080
   
4. Rebuild the frontend if running from source:
   cd src/dashboard/frontend && npm run build
   
5. Ensure all dashboard dependencies are installed:
   pip install voicegateway[dashboard]
   

​

“MCP tool not found”

1. Verify the MCP server is running:
   voicegw mcp --transport stdio
   
2. For HTTP/SSE transport, check the endpoint:
   curl http://localhost:8090/sse
   
3. Check your agent’s MCP configuration. For Claude Code, add to ~/.claude/config.json:
   {
     "mcpServers": {
       "voicegateway": {
         "command": "voicegw",
         "args": ["mcp", "--transport", "stdio"]
       }
     }
   }
   
4. If using HTTP transport with auth, ensure VOICEGW_MCP_TOKEN matches between server and client
5. Restart the MCP server and the coding agent

​

asyncio event loop errors

1. attach() is synchronous and safe to call from inside a running event loop (Jupyter, FastAPI handlers). Build your native provider plugins and AgentSession as usual, then call attach(session):
   from livekit.plugins import deepgram
   from voicegateway import attach
   
   stt = deepgram.STT(model="nova-3")
   # ... build the AgentSession with your plugins ...
   attach(session, project="my-agent")
   
   If you see “already running event loop” errors during setup (rare), isolate it in a separate thread or apply nest_asyncio (see below).
2. If running in a script (not an async framework), use asyncio.run():
   import asyncio
   asyncio.run(main())
   
3. In Jupyter notebooks, use nest_asyncio:
   import nest_asyncio
   nest_asyncio.apply()
   
4. If running tests, ensure asyncio_mode = "auto" is set in pyproject.toml

​

”livekit plugin missing” / ModuleNotFoundError

pip install livekit-plugins-deepgram

pip install livekit-plugins-openai livekit-plugins-deepgram livekit-plugins-cartesia

pip list | grep livekit

​

“Configuration validation failed”

1. Check YAML syntax: use a YAML linter or python -c "import yaml; yaml.safe_load(open('voicegw.yaml'))"
2. Required sections: providers, models (with stt, llm, tts sub-keys)
3. Environment variable references: ensure ${VAR_NAME} variables are actually set:
   echo $OPENAI_API_KEY  # Should not be empty
   
4. Compare against the annotated reference config:
   voicegw init --full --output /tmp/voicegw.reference.yaml
   diff /tmp/voicegw.reference.yaml voicegw.yaml
   
   init takes only --output/-o and --full; there is no --diff.
5. Common mistakes:
   • Using tabs instead of spaces (YAML requires spaces)
   • Missing colon after a key
   • Incorrect indentation level
   • Referencing a provider in models that is not defined in providers

​

Rate limiting errors

1. Configure rate limits in voicegw.yaml to stay under provider quotas:
   rate_limiting:
     openai:
       requests_per_minute: 60
   
2. Add fallback providers so requests can be routed elsewhere:
   fallbacks:
     llm:
       - anthropic/claude-3.5-sonnet
       - groq/llama-3.1-70b-versatile
   
3. Check your provider dashboard for current usage and limits

​

Database locked errors

1. Ensure only one VoiceGateway server instance writes to the database
2. If running multiple instances, give each its own db_path:
   cost_tracking:
     db_path: /data/voicegw-instance-1.db
   
3. Or use the VOICEGW_DB_PATH environment variable:
   VOICEGW_DB_PATH=/data/voicegw-1.db voicegw serve --port 8080
   
4. The dashboard reads the database (read-only) and should not cause locks

​

Related pages

• FAQ
• Installation
• Quickstart
• Contributing
• Changelog