# Troubleshooting

This page lists common Conversation Orchestrator errors, including authentication issues, missing conversations, voice-specific problems, and asynchronous operation failures.

## Inspect events in the Debugger

To investigate a Conversation Orchestrator problem after the fact, you can use the [Twilio Debugger](/docs/usage/troubleshooting/debugging-your-application). The Debugger shows info, warning, and error events for conversations, participants, communications, and profile resolution on your account. Open it from **Develop > Troubleshoot > Debugger** in the Twilio Console, or from the **Debugger** tab in the [Twilio Workbench](/docs/usage/workbench). The Debugger is available in the US1 region only.

Filter by source `conversation-orchestrator` to see only Conversation Orchestrator events. The following event types are available:

| Event type                                                             | Queryable fields                               | When it fires                                                         |
| ---------------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------- |
| `conversation.created`, `conversation.updated`, `conversation.deleted` | `id`, `status`                                 | A conversation is created, changes state, or is deleted.              |
| `participant.created`, `participant.updated`, `participant.removed`    | `id`, `conversationId`, `participantType`      | A participant joins, changes, or leaves a conversation.               |
| `communication.created`, `communication.updated`                       | `id`, `conversationId`, `author.participantId` | A message or transcription is added or its delivery status changes.   |
| `diagnostic`                                                           | `resourceSid`, `errorCode`, `status`           | A non-fatal operational signal, such as a profile resolution outcome. |

Diagnostic events have a Twilio error code. Look up any code in the [Error and Warning Dictionary](/docs/api/errors). Conversation Orchestrator codes are in the `530xxx` range. To trace one request end to end, match the `requestId` or `correlationId` on each event to the Twilio request ID returned on API responses and set on outbound webhook headers.

## Error response structure

All Conversation Orchestrator errors follow this format:

```json
{
  "code": 20003,
  "httpStatusCode": 401,
  "message": "Terms of service have not been accepted.",
  "userError": true,
  "params": { "field": "termsOfService", "value": "not_accepted" }
}
```

## Common Twilio error codes

| Code    | Meaning                        | What to do                                                                                                                                                                    |
| ------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `20003` | Terms of Service not accepted. | In the [Twilio Console](https://1console.twilio.com), open Conversation Orchestrator and accept the Predictive and Generative AI/ML Features Addendum. Then wait 1-2 minutes. |
| `21614` | Invalid phone number.          | Use [E.164](/docs/glossary/what-e164) format (for example, `+15551234567`), with no spaces or dashes. Validate with the [Twilio Lookup API](/docs/lookup/v2-api).             |

## Common HTTP status codes

| Status | Meaning                | What to do                                                                                                                                                                                          |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Authentication failed. | Verify your Account SID (starts with `AC`, 34 characters) and Auth Token, and that you're using HTTP Basic Auth.                                                                                    |
| `404`  | Resource not found.    | Check the resource ID format and that the resource wasn't deleted. Prefixes: `mem_store_`, `mem_profile_`, `conv_configuration_`, `conv_conversation_`, `conv_participant_`, `conv_communication_`. |

## No conversation created after sending a message

If you send an SMS or make a call but no conversation appears, check these in order:

1. **Check that capture rules match.** Fetch your configuration and inspect `channelSettings.CHANNEL_NAME.captureRules`. Make sure your capture rules are bidirectional: one with your Twilio address as `from`, one as `to`.
2. **Verify E.164 phone number format.**  Capture rules compare addresses exactly, so your Twilio number must include the `+` and country code.
3. **Allow for propagation.** After creating or updating a configuration, wait 5-10 seconds before sending test traffic.
4. **Check for overlapping capture rules across configurations.** If multiple configurations match the same address, Conversation Orchestrator doesn't guarantee which one handles the traffic.

If the conversation exists but doesn't appear in the default list, search by the original Twilio Message or Call SID using the `channelId` query parameter on the [Conversations](/docs/api/conversations/v2/Conversation) endpoint.

## Voice conversation has no communications

Conversation Orchestrator creates voice communications from real-time transcription, not from the call itself. This means a communication is only created when someone speaks and that speech is transcribed. If the call is silent or transcription isn't running, no communications appear. To test, make sure someone speaks during the call and confirm that your voice capture rules are set up correctly.

## Voice conversation stuck in ACTIVE

The timeout clock for voice only starts when a transcription event is received. A silent call produces no transcription, so the conversation never transitions out of `ACTIVE`.

You can resolve this in one of the following ways:

* Set `"statusTimeouts": null` on the `VOICE` channel so conversations close as soon as the final transcription event arrives.
* Close stuck conversations manually. See [Close conversations with the API](/docs/conversations/orchestrator/concepts/lifecycle#close-conversations-with-the-api).

For the underlying architecture, see [Voice timeouts behave differently](/docs/conversations/orchestrator/concepts/lifecycle#voice-timeouts-behave-differently).

## Asynchronous operation issues

Some API requests run asynchronously and can fail or stall. For background on how these requests work, see [Asynchronous operations](/docs/conversations/orchestrator/concepts/async-operations).

* **Stuck in PENDING.** Wait at least 30 seconds. If the operation is still `PENDING`, contact [Twilio Support](https://support.twilio.com) with the `operationId`, timestamp, and Account SID.
* **Fails immediately.** Inspect the error message in the operation response. Common causes are invalid phone numbers, a missing or invalid `memoryStoreId`, and malformed capture rules.
* **Completed but no resource ID.** This is a known limitation for configuration `POST` and `PUT` operations. For the workaround, see [Asynchronous operations](/docs/conversations/orchestrator/concepts/async-operations#known-limitation-configuration-operations-dont-return-a-resource-id).

## Participant has no profileId

Only `CUSTOMER` participants get profiles. Profile resolution is best-effort and asynchronous, so briefly null values are normal. Check:

1. The participant's `type` is `CUSTOMER`.
2. The configuration has a `memoryStoreId` set.
3. The address matches the profile trait format exactly (E.164 with `+` for phone, and so on).
4. The participant was created through active ingestion. In passive ingestion, profiles aren't created automatically; the type must be explicit. See [Profiles](/docs/conversations/orchestrator/concepts/profiles).

## Memory extraction not producing observations

If memory extraction is on but no observations appear on the profile, check the following in order:

1. **Verify that `memoryExtractionEnabled` is `true`.** Fetch the configuration and inspect the field.
2. **Verify that the memory store is in the `ACTIVE` state.** Send a `GET` request to `/v1/Stores/{storeId}` and check `status`.
3. **Verify that the `memoryStoreId` is correct.** Cross-reference the store ID in the configuration with the actual store.
4. **Confirm that the conversation reached the extraction trigger state.** Fetch the conversation and check its `status`. If the conversation is still `ACTIVE`, extraction hasn't fired yet.
5. **Verify that the `CUSTOMER` participant has a `profileId`.** If `profileId` is `null`, profile resolution failed and extraction has no target profile.

For issues with what gets extracted (not whether extraction fires), see [Conversation Memory](/docs/conversations/memory).

## Intelligence operators not firing

1. **Verify `intelligenceConfigurationIds` is present on the configuration.** Fetch the configuration and inspect the field. A prior `PUT` request that omitted this field would have deleted it. See [Updating a configuration](/docs/conversations/orchestrator/concepts/core#updating-a-configuration-put-not-patch).
2. **Check whether the configuration was updated after the conversation was created.** Conversations pin the configuration version at creation. New intelligence configurations only apply to new conversations.
3. **Verify the operator is configured for the correct trigger.** The `COMMUNICATION` trigger fires once per communication. The `CONVERSATION_END` trigger fires on `CLOSED`. Verify you're waiting for the right lifecycle event.

## Conversations merge unexpectedly

If conversations from different customers land in the same conversation, check the following causes:

| Cause                                                                | Fix                                                                                                               |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `GROUP_BY_PROFILE` and multiple customers share the same profile.    | Verify identity traits are unique. Two customers shouldn't share a phone number trait on the same profile.        |
| `GROUP_BY_PARTICIPANT_ADDRESSES` and customers share a phone number. | This is expected behavior for address-based grouping. Switch to `GROUP_BY_PROFILE` for identity-level separation. |

## CLIENT or SIP calls aren't captured

Passive voice capture rules default to PSTN matching. To capture CLIENT and `PUBLIC_SIP` calls, include explicit `callType` metadata in the rule.

A rule without `callType` doesn't capture CLIENT calls:

```json
{ "from": "*", "to": "+15551234567" }
```

A rule that captures CLIENT calls:

```json
{ "from": "*", "to": "agent-1", "metadata": { "callType": "CLIENT" } }
```

A rule that captures SIP calls:

```json
{ "from": "*", "to": "+15551234567", "metadata": { "callType": "PUBLIC_SIP" } }
```

To troubleshoot this problem, take the following steps:

1. Verify that the `callType` metadata is present on the capture rule.
2. Verify that the `to` address matches the actual address format for that call type.
3. For CLIENT calls with dynamic identities, switch to [active TwiML ingestion](/docs/conversations/orchestrator/guides/active-creation#optional-ingest-voice-calls-with-twiml) instead of passive capture rules.

## More voice communications than expected

Conversation Relay writes one communication per text-to-speech (TTS) fragment, not one communication per complete agent response. A single agent utterance might produce three to five communications depending on how the TTS engine chunks the text.

This behavior has three effects:

* Communication lists are longer than expected (3-5x for agent turns).
* Intelligence operators with the `COMMUNICATION` trigger fire once per fragment, which multiplies operator cost.
* Webhook handlers (`statusCallbacks`) receive more events than anticipated.

If you need per-turn analysis, use the `CONVERSATION_END` trigger on intelligence operators instead of the `COMMUNICATION` trigger.

## Related resources

* [Asynchronous operations](/docs/conversations/orchestrator/concepts/async-operations): Polling, idempotency, and SDK examples.
* [Core concepts](/docs/conversations/orchestrator/concepts/core): The object model.
* [Profiles](/docs/conversations/orchestrator/concepts/profiles): How participant types and profiles resolve.
* [Conversation lifecycle](/docs/conversations/orchestrator/concepts/lifecycle): Timeouts, voice behavior, manual close.