Skip to main content

​
Troubleshooting

Common issues and their solutions. If your problem is not listed here, open an issue or check the FAQ.

​
”No voicegw.yaml found”

Error: ConfigError: No voicegw.yaml found Cause: VoiceGateway cannot find a configuration file. Fix: VoiceGateway searches for config in this order:
  1. ./voicegw.yaml (current working directory)
  2. ~/.config/voicegateway/voicegw.yaml
  3. /etc/voicegateway/voicegw.yaml
Generate a starter config: 
voicegw init
Or set an explicit path: 
export VOICEGW_CONFIG=/path/to/voicegw.yaml
voicegw serve

​
“Provider not configured”

Error: ValueError: Unknown provider 'xyz'. Available: anthropic, assemblyai, cartesia, deepgram, elevenlabs, groq, kokoro, ollama, openai, piper, whisper Cause: The provider name in your model ID does not match any registered provider, or the provider is not listed in your voicegw.yaml. Fix:
  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. If using a new provider, install the extra: pip install voicegateway[openai]

​
”Budget exceeded”

Error: BudgetExceededError: Project 'my-app' has exceeded its daily budget of $10.00 Cause: The project’s daily spending has hit the configured daily_budget and budget_action is set to block. Fix:
  • 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”

Error: ConnectionRefusedError: [Errno 111] Connection refused when using Ollama Cause: Ollama is not running or is listening on a different address. Fix:
  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

Error: cryptography.fernet.InvalidToken or Failed to decrypt API key Cause: The encryption key has changed or the stored encrypted value is corrupted. Fix:
  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

Error: Dashboard container exits immediately or returns 502. Cause: Usually a port conflict, missing config mount, or the frontend build is missing. Fix:
  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”

Error: Coding agent reports the tool is not available or returns an empty tool list. Cause: The MCP server is not running, the transport configuration is wrong, or the agent is not connected. Fix:
  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

Error: RuntimeError: There is no current event loop in thread 'MainThread' or RuntimeError: This event loop is already running Cause: Mixing synchronous and asynchronous code, or running in an environment that manages its own event loop (Jupyter, some web frameworks). Fix:
  1. The voicegateway.inference.STT/LLM/TTS factories are synchronous and handle event loop bridging internally on first construction (loading the merged config). This usually works fine inside a running event loop (Jupyter, FastAPI handlers, etc.): 
    from voicegateway import inference

stt = inference.STT("deepgram/nova-3")
    If you see “already running event loop” errors during the first factory call (rare), isolate the setup 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

Error: ModuleNotFoundError: No module named 'livekit.plugins.deepgram' Cause: The provider’s LiveKit plugin SDK is not installed. Fix: Install the specific provider extra: 
pip install voicegateway[deepgram]
Or install all cloud providers: 
pip install voicegateway[cloud]
Available extras: openai, deepgram, anthropic, groq, cartesia, elevenlabs, assemblyai, whisper, kokoro, piper. Check what is installed: 
pip list | grep livekit

​
“Configuration validation failed”

Error: ConfigError: Configuration validation failed: ... Cause: The voicegw.yaml file has structural errors, missing required fields, or invalid values. Fix:
  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 example config: 
    voicegw init --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

Error: RateLimitError: Provider 'openai' rate limit exceeded or HTTP 429 from the provider. Cause: Too many requests to a provider in a short time. Fix:
  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

Error: sqlite3.OperationalError: database is locked Cause: Multiple processes writing to the same SQLite database file. Fix:
  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