# Troubleshooting

This guide helps you identify and resolve issues when working with TAC. If you encounter problems not covered here, contact Twilio Support.

## Missing dependencies

**Issue**: Unable to import TAC in your code.

The following are common causes:

* TAC not installed: The package hasn't been installed in your development environment.
* Wrong runtime environment: You're running the server with a different runtime than where TAC is installed (for example, system-level vs. project-level environment).
* Environment not activated: TAC was installed in an isolated environment (virtual environment, container, etc.) but that environment isn't active.
* PATH issues: The runtime executable you're using doesn't match the package manager that installed TAC.

**Solution**: Install TAC and its dependencies.

## Python

**uv (recommended)**:

```bash
uv init
uv add twilio-agent-connect[server]
```

**pip/venv (alternative)**:

```bash
python -m venv .venv
source .venv/bin/activate
pip install twilio-agent-connect[server]
```

## TypeScript

```bash
npm install twilio-agent-connect
```

## Missing environment variables

**Issue**: Your application crashes with configuration errors.

**Solution**: Create a `.env` file with all required environment variables. See [Configure environment variables](/docs/conversations/agent-connect/build-with-tac#configure-environment-variables) for the complete list.

## Python

Required variables:

```text
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=your_api_key_secret
TWILIO_PHONE_NUMBER=+1234567890
TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxxxxxxxxxxxxxxxxx
```

## TypeScript

Required variables:

```text
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_API_KEY=SKxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_API_SECRET=your_api_key_secret
TWILIO_PHONE_NUMBER=+1234567890
TWILIO_CONVERSATION_CONFIGURATION_ID=conv_configuration_xxxxxxxxxxxxxxxxxx
```

## Webhook issues

### Webhooks not receiving events (SMS)

**Issue**: Your server is running, but SMS webhooks are not arriving.

**Common causes:**

* Twilio phone number is not added to the Conversations service.
* Webhook URL is not set up in the Conversations service.
* Local server doesn't have the correct webhook URL configured in the Conversations service.

**Solution:**

* Add your phone number to the Conversations service (if not already added).
* Set the webhook URL in the Conversations service:

  ```text
  https://your-ngrok-domain/webhook
  ```

### Server not publicly accessible

**Issue**: Not receiving webhook events from Twilio when you text or call your Twilio number.

**Common cause**: Your local development server isn't publicly accessible from the internet.

**Solution** (for local development):

Use ngrok to expose your local server. See [Expose your local server with ngrok](/docs/conversations/agent-connect/quickstart#expose-your-local-server-with-ngrok) for setup instructions.

```bash
# Start your server first, then in a new terminal:
ngrok http 8000
```

Update the Twilio Console with your ngrok URL:

```text
https://your-ngrok-domain.ngrok.app/webhook
```

## Voice call issues

### Voice calls not connecting

**Issue**: Calls to your Twilio number don't connect or drop immediately.

**Solution**: Check TwiML URL configuration.

**Verify voice webhook configuration**:

1. Log in to Twilio Console.
2. Navigate to **Numbers and Senders**.
3. Select your phone number.
4. Go to **Configuration details**.
5. Click **Edit details** in **Voice Configuration**.
6. Select **Webhook** as the method to configure your voice calls.
7. Verify that your webhook URL is set correctly and that the HTTP method is set to `POST`.

Correct webhook URL format:

```text
https://your-ngrok-domain/twiml
```

**Webhook configuration checklist**:

* URL starts with `https://` and not `http://`.
* URL ends with the `/twiml` endpoint path.
* HTTP method is set to `POST`.

## Memory retrieval issues

### Memory not returning data

**Issue**: The memory response in your callback is `None` (Python) or `undefined` (TypeScript).

**Common causes:**

* Conversation Memory is not configured for your account.
* Memory retrieval is not turned on in your channel configuration.
* No profile exists for the caller's phone number in Conversation Memory.

**Solution:**

## Python

* Verify that `TWILIO_CONVERSATION_CONFIGURATION_ID` is set in your `.env` file.
* Set `memory_mode="always"` in your channel config (for example, `VoiceChannelConfig(memory_mode="always")`).
* Check that a profile with matching contact information exists in [Conversation Memory](/docs/conversations/memory).
* Turn on debug logging with `TWILIO_LOG_LEVEL=debug` and check for memory retrieval log entries.

## TypeScript

* Verify that `TWILIO_CONVERSATION_CONFIGURATION_ID` is set in your `.env` file and that the Conversation Configuration has a Memory Store linked.
* Check that a profile with matching contact information exists in [Conversation Memory](/docs/conversations/memory).
* Turn on debug logging with `TWILIO_LOG_LEVEL=debug` and check for memory retrieval log entries.

## Tool execution issues

### Custom tools not called by the LLM

**Issue**: Your custom tools are defined but the LLM never calls them.

**Common causes:**

* The tools are not included in the LLM request.
* The tool descriptions are unclear or don't match the conversation context.

**Solution:**

* Verify that you're passing the tools to your LLM's API request (for example, in the `tools` parameter for OpenAI).
* Write clear, specific tool descriptions that help the LLM understand when to use each tool.
* Test by explicitly asking your agent to perform the action the tool handles.

## Escalation issues

### Handoff not triggering

**Issue**: The LLM calls the handoff tool but the call doesn't route to your Studio Flow.

**Common causes:**

* `TWILIO_STUDIO_HANDOFF_FLOW_SID` is not set in your environment.
* The Studio Flow SID is incorrect or the flow is not published.
* The handoff tool is not created with the correct `tac` and `session` arguments.

**Solution:**

* Verify that `TWILIO_STUDIO_HANDOFF_FLOW_SID` is set in your `.env` file and starts with `FW`.
* Confirm the Studio Flow is published and active.
* Check that you're passing both the `tac` instance and the current `context` session to the tool factory:

```python
from tac.tools import create_studio_handoff_tool

handoff_tool = create_studio_handoff_tool(tac, context)
```

### Duplicate messages after handoff

**Issue**: After a voice handoff to Flex, each message appears twice in the conversation thread.

**Cause**: Your Conversation Configuration has Voice captureRules enabled alongside TAC's Conversation Relay. Both paths hydrate the same conversation, resulting in duplicate messages.

**Solution**: Remove Voice captureRules from your Conversation Configuration when using TAC with Conversation Relay. TAC handles voice conversation hydration through Conversation Relay automatically.