> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Debugging voice agents

> Diagnose voice assistant issues with call, API request, and webhook logs, component testing, and provider status checks in the Vapi Dashboard.

## Overview

Voice agents involve multiple AI systems working together—speech recognition, language models, and voice synthesis. When something goes wrong, systematic debugging helps you quickly identify and fix the root cause.

**Most common issues fall into these categories:**

#### Speech & Understanding

* Agent doesn't understand user input correctly
* Responses are inappropriate or inconsistent
* Agent sounds robotic or unnatural

#### Technical & Integration

* Call quality issues or audio problems
* Tool integrations failing or returning errors
* Unexpected behavior or configuration errors

## Quick diagnostics

Start with these immediate checks before diving deeper:

#### Test in dashboard

Test your voice agent directly in the [dashboard](https://dashboard.vapi.ai/):

#### Assistants

Click "Talk to Assistant" to test

**Benefits:**

* Eliminates phone network variables
* Provides real-time transcript view
* Shows tool execution results immediately

#### Check logs

Use the [Logs overview](/observability/logs/overview) to choose the right log, then open **Logs** in the [Dashboard](https://dashboard.vapi.ai/):

#### [Calls](/observability/logs/call-logs)

Review call transcripts, durations, and error messages

#### [API](/observability/logs/api-request-logs)

Check logged API requests and responses for integration issues

#### [Webhooks](/observability/logs/webhook-logs)

Verify logged webhook deliveries and server responses

#### Test individual components

Use [dashboard](https://dashboard.vapi.ai/) testing features:

#### [Simulations](/observability/simulations-overview)

Test outcomes across complete conversations

#### [Evals](/observability/evals-quickstart)

Test decisions at specific conversation points

#### [Tool testing](#tool-testing)

Test supported tools with sample data

#### Verify provider status

Check if AI service providers are experiencing issues:

**Core Services:**

* Visit [Vapi Status Page](https://status.vapi.ai/) for Vapi service status

**Provider Status Pages:**

* [OpenAI Status](https://status.openai.com/) for OpenAI language models
* [Anthropic Status](https://status.anthropic.com/) for Anthropic language models
* [ElevenLabs Status](https://status.elevenlabs.io/) for ElevenLabs voice synthesis
* [Deepgram Status](https://status.deepgram.com/) for Deepgram speech-to-text
* [Gladia Status](https://status.gladia.io/) for Gladia speech-to-text
* And other providers' status pages as needed

## Dashboard debugging resources

The [Vapi dashboard](https://dashboard.vapi.ai/) provides powerful debugging features to help you identify and fix issues quickly:

### Call logs

Open [**Logs → Calls**](/observability/logs/call-logs) to:

* Review available call transcripts
* Check call duration and completion status
* Identify where calls failed or ended unexpectedly
* See tool execution results and errors
* Analyze conversation flow

### API request logs

Open [**Logs → API**](/observability/logs/api-request-logs) to:

* Inspect logged API requests and responses
* Review recorded `401` and `403` responses
* Verify request payloads and response codes
* Debug integrations that call the Vapi API

### Webhook logs

Open [**Logs → Webhooks**](/observability/logs/webhook-logs) to:

* Verify logged webhook deliveries to your server
* Check server response codes and timing
* Debug webhook authentication issues
* Monitor event delivery failures

Use the Vapi CLI to forward webhooks to your local development server:

```bash
# Terminal 1: Create tunnel (e.g., with ngrok)
ngrok http 4242

# Terminal 2: Forward webhooks
vapi listen --forward-to localhost:3000/webhook
```

> **Note**
>
> `vapi listen` is a local forwarder that requires a separate tunneling service. Update your webhook URLs in Vapi to use the tunnel's public URL. [Learn more →](/cli/webhook)

### Simulations and Evals

Use **Simulations** to reproduce a problem across a complete conversation and
check the final outcome. Use **Evals** to isolate a specific decision, such as
choosing a tool, asking for missing information, or escalating the call.

See [testing voice agents](/test/voice-testing) for guidance on choosing a test
and turning production failures into regression coverage.

### Tool testing

The Dashboard can test API request, function, and Model Context Protocol (MCP) tools. To test one from **Tools**:

* Select the tool.
* Select **Test**.
* Configure and run the test in the panel.
* Review the response and any error details.

## Speech and language issues

| Problem                    | Symptoms                                                                                    | Solution                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Transcription accuracy** | Incorrect words in transcripts, missing words/phrases, poor performance with accents        | Switch to more accurate transcriber.                                                                             |
| **Intent recognition**     | Agent responds to wrong intent, fails to extract variables                                  | Make the system prompt more specific; use clear enum values; adjust the temperature to ensure consistent outputs |
| **Response quality**       | Different responses to identical inputs, agent forgets context, doesn't follow instructions | Review system prompt specificity; check model configuration; adjust temperature to achieve consistency           |

**Debug steps for response quality:**

1. **Review system prompt** - Navigate to your assistant in the [dashboard](https://dashboard.vapi.ai/) and check the system prompt specificity
2. **Check model configuration** - Scroll down to `Model` section and verify:
   * You're using an appropriate model (e.g., `gpt-4o`)
   * `Max Tokens` is sufficient for response length
   * Necessary tools are enabled and configured correctly

| Response Issue         | Solution                                                                                     |
| ---------------------- | -------------------------------------------------------------------------------------------- |
| **Responses too long** | Add "Keep responses under X words" to system prompt                                          |
| **Robotic speech**     | Switch to a different voice provider                                                         |
| **Forgetting context** | Use models with larger context windows                                                       |
| **Wrong information**  | Check tool outputs and knowledge base accuracy in [call logs](/observability/logs/call-logs) |

## Tool and variable debugging

| Problem Type            | Issue                                               | Solution                                                                                                                                                                    |
| ----------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tool execution**      | Tools failing, HTTP errors, parameter issues        | Open [**Logs → Calls**](/observability/logs/call-logs) and check the **Logs** tab. For API request, function, and MCP tools, use **Test**, then validate the configuration. |
| **Variable extraction** | Variables not extracted, wrong values, missing data | Be specific in variable descriptions, use distinct enum values, add validation prompts                                                                                      |

**Variable extraction details:**

| Problem                        | Cause                    | Solution                                                                 |
| ------------------------------ | ------------------------ | ------------------------------------------------------------------------ |
| **Variables not extracted**    | Unclear description      | Be specific in variable descriptions: "Customer's 10-digit phone number" |
| **Wrong variable values**      | Ambiguous enum options   | Use distinct enum values: "schedule", "cancel", "reschedule"             |
| **Missing required variables** | User didn't provide info | Add validation prompts to request missing data                           |

## Common error patterns

| Error Pattern                    | Likely Cause             | Quick Fix                                                                         |
| -------------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| **Agent misinterpreting speech** | Speech recognition issue | Check transcriber model, add custom keyterms                                      |
| **Irrelevant responses**         | Poor prompt engineering  | Be more specific in system prompt                                                 |
| **Call drops immediately**       | Configuration error      | Check all required fields in assistant settings                                   |
| **Tool errors**                  | API integration issue    | Use **Test** for API request, function, and MCP tools, then verify endpoint URLs. |
| **Long silences**                | Model processing delay   | Use faster models or reduce response length                                       |

> **Tip**
>
> For a complete list of error codes and what they mean, see [Call end reasons](/calls/call-ended-reason). To diagnose a failed call by symptom (e.g., "call dropped mid-conversation" or "assistant went silent"), see [Troubleshoot call errors](/calls/troubleshoot-call-errors).

## Getting help

When you're stuck:

#### [Discord community](https://discord.gg/v5Ee6FhAZt)

Ask other developers for help in the Vapi Discord community

#### [API Reference](/api-reference)

Check the API reference for detailed configuration options

#### [Status Page](https://status.vapi.ai/)

Check real-time status of Vapi services and AI providers

**Before asking for help:**

* Include the call ID and timestamp from [**Logs → Calls**](/observability/logs/call-logs)
* Describe expected vs. actual behavior
* Share relevant configuration (without API keys)
* Include error messages from [dashboard](https://dashboard.vapi.ai/) logs