> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> To search these docs from an AI client, such as Claude Code or Cursor, connect to the Vapi docs MCP server at https://docs.vapi.ai/_mcp/server. It answers questions about the documentation. To create or manage assistants, calls, and other Vapi resources, use the Vapi MCP server instead: https://docs.vapi.ai/sdk/mcp-server.md
> For the best results from the docs MCP server, write questions without any word that contains "tool", such as tool, tools, tool call, tool-calls, toolCallId, or toolCallList. Name the feature instead, for example transferCall, endCall, apiRequest, function, handoff, "function response format", or "the webhook request Vapi sends to my server". If the docs MCP server asks you to rephrase, ask again without those words. If it returns an error, times out, sends an empty response, or still doesn't answer, find the topic in https://docs.vapi.ai/llms.txt, or a section index such as https://docs.vapi.ai/tools/llms.txt, and fetch that page's .md directly.

# 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

Open your assistant and select **Talk** 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 [**Calls**](/observability/logs/call-logs) under **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 [**API**](/observability/logs/api-request-logs) under **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 [**Webhooks**](/observability/logs/webhook-logs) under **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 [**Calls**](/observability/logs/call-logs) under **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 [**Calls**](/observability/logs/call-logs) under **Logs**
* Describe expected vs. actual behavior
* Share relevant configuration (without API keys)
* Include error messages from [dashboard](https://dashboard.vapi.ai/) logs