> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicegateway.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common VoiceGateway issues and their fixes, covering missing config, unconfigured providers, budget limits, Ollama connections, decryption errors, Docker dashboard crashes, MCP tooling, asyncio loops, missing plugins, config validation, rate limits, and database locks.

# Troubleshooting

Common issues and their solutions. If your problem is not listed here, [open an issue](https://github.com/mahimailabs/voicegateway/issues) or check the [FAQ](/reference/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:

```bash theme={null}
voicegw init
```

Or set an explicit path:

```bash theme={null}
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:
   ```yaml theme={null}
   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`:
  ```yaml theme={null}
  projects:
    my-app:
      daily_budget: 50.00
  ```
* **Switch to warn mode** to log warnings instead of blocking:
  ```yaml theme={null}
  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:
   ```bash theme={null}
   ollama serve
   ```
2. Verify it is running:
   ```bash theme={null}
   curl http://localhost:11434/api/tags
   ```
3. If Ollama is on a different host or port, update your config:
   ```yaml theme={null}
   providers:
     ollama:
       base_url: http://your-host:11434
   ```
4. If using Docker Compose with the `local` profile:
   ```bash theme={null}
   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:
   ```bash theme={null}
   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:
   ```bash theme={null}
   docker compose logs dashboard
   ```
2. Ensure the config file is mounted in your `docker-compose.yml`:
   ```yaml theme={null}
   services:
     voicegateway:
       volumes:
         - ./voicegw.yaml:/app/voicegw.yaml:ro
   ```
   Then restart:
   ```bash theme={null}
   docker compose up -d
   ```
3. Check port availability (default: 8080, the daemon's serve port):
   ```bash theme={null}
   lsof -i :8080
   ```
4. Rebuild the frontend if running from source:
   ```bash theme={null}
   cd src/dashboard/frontend && npm run build
   ```
5. Ensure all dashboard dependencies are installed:
   ```bash theme={null}
   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:
   ```bash theme={null}
   voicegw mcp --transport stdio
   ```
2. For HTTP/SSE transport, check the endpoint:
   ```bash theme={null}
   curl http://localhost:8090/sse
   ```
3. Check your agent's MCP configuration. For Claude Code, add to `~/.claude/config.json`:
   ```json theme={null}
   {
     "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.):
   ```python theme={null}
   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()`:
   ```python theme={null}
   import asyncio
   asyncio.run(main())
   ```
3. In Jupyter notebooks, use `nest_asyncio`:
   ```python theme={null}
   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:

```bash theme={null}
pip install voicegateway[deepgram]
```

Or install all cloud providers:

```bash theme={null}
pip install voicegateway[cloud]
```

Available extras: `openai`, `deepgram`, `anthropic`, `groq`, `cartesia`, `elevenlabs`, `assemblyai`, `whisper`, `kokoro`, `piper`.

Check what is installed:

```bash theme={null}
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:
   ```bash theme={null}
   echo $OPENAI_API_KEY  # Should not be empty
   ```
4. **Compare against the example config:**
   ```bash theme={null}
   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:
   ```yaml theme={null}
   rate_limiting:
     openai:
       requests_per_minute: 60
   ```
2. Add fallback providers so requests can be routed elsewhere:
   ```yaml theme={null}
   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`:
   ```yaml theme={null}
   cost_tracking:
     db_path: /data/voicegw-instance-1.db
   ```
3. Or use the `VOICEGW_DB_PATH` environment variable:
   ```bash theme={null}
   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](/reference/faq)
* [Installation](/guide/installation)
* [Quick Start](/guide/quick-start)
* [Contributing](/contributing/)
* [Changelog](https://github.com/mahimailabs/voicegateway/blob/main/CHANGELOG.md)