> 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 full documentation content, see https://docs.vapi.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Debugging voice agents

## 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:**

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

- Call quality issues or audio problems
- Tool integrations failing or returning errors
- Workflow logic not executing as expected

## Quick diagnostics

Start with these immediate checks before diving deeper:

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

Click "Talk to Assistant" to test

Click "Call" to test workflow

**Benefits:**

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

Navigate to the `Observe` section in your [dashboard](https://dashboard.vapi.ai/) sidebar:

Review call transcripts, durations, and error messages

Check API requests and responses for integration issues

Verify webhook deliveries and server responses

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

Automated testing for assistants

Test tools with sample data

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

Navigate to `Observe > Call Logs` to:

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

### API Logs

Navigate to `Observe > API Logs` to:

* Monitor all API requests and responses
* Check for authentication errors
* Verify request payloads and response codes
* Debug integration issues with external services

### Webhook Logs

Navigate to `Observe > Webhook Logs` to:

* Verify 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
```

`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)

### Voice Test Suites

Navigate to `Test > Voice Test Suites` to:

* Run automated tests on your assistants (not available for workflows)
* Test conversation flows with predefined scenarios
* Verify assistant behavior across different inputs
* Monitor performance over time

### Tool Testing

For any tool in your `Tools` section:

* Navigate to `Tools > [Select Tool]`
* Use the `Test` button to send sample payloads
* Verify tool responses and error handling
* Debug parameter extraction and API calls

## 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, workflow routing to wrong nodes | Make system prompt / node 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 / node prompt specificity; check model configuration; adjust temperature to achieve consistency       |

**Debug steps for response quality:**

1. **Review system prompt** - Navigate to your assistant/workflow 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 via `Call Logs` |

## Tool and workflow debugging

| Problem Type            | Issue                                                                | Solution                                                                                                                                              |
| ----------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tool execution**      | Tools failing, HTTP errors, parameter issues                         | Navigate to `Observe > Call Logs` and check tool execution section, test tools individually at `Tools > [Select Tool] > Test`, validate configuration |
| **Variable extraction** | Variables not extracted, wrong values, missing data                  | Be specific in variable descriptions, use distinct enum values, add validation prompts                                                                |
| **Workflow logic**      | Wrong node routing, conditions not triggering, variables not passing | Use `Call Logs` to trace conversation path, verify edge conditions are clear, check global node conflicts                                             |

**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/workflow settings |
| **Tool errors**                  | API integration issue    | Test tools individually, verify endpoint URLs            |
| **Long silences**                | Model processing delay   | Use faster models or reduce response length              |

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:

Join the Vapi Discord for real-time help from the community and team

Check the API reference for detailed configuration options

Check real-time status of Vapi services and AI providers

**Before asking for help:**

* Include call ID and timestamp from `Call Logs` in your [dashboard](https://dashboard.vapi.ai/)
* Describe expected vs. actual behavior
* Share relevant configuration (without API keys)
* Include error messages from [dashboard](https://dashboard.vapi.ai/) logs