> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find the fix by symptom.

Start from the symptom, land on the fix.

## Quick index

| Symptom                                                  | Go to                                                                           |
| -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Device missing from the client, tool list empty or short | [Devices & Connectivity](/guides/troubleshooting/devices)                       |
| `device_offline`, `device_paused`                        | [Devices & Connectivity](/guides/troubleshooting/devices)                       |
| Task stuck `pending`, `queue_wait_exceeded`              | [Tasks & Sessions](/guides/troubleshooting/tasks)                               |
| Task stays paused, monitor returns "early"               | [Tasks & Sessions](/guides/troubleshooting/tasks)                               |
| Phone asks for input (`needs_user_control`)              | [Tasks & Sessions](/guides/troubleshooting/tasks#the-phone-asks-for-user-input) |
| `session_not_found_or_inactive`, `task_not_found`        | [Tasks & Sessions](/guides/troubleshooting/tasks)                               |
| `401`/`403`, `insufficient_scope`, `Invalid token`       | [Authentication](/guides/troubleshooting/authentication)                        |
| Connection times out, transport errors, client quirks    | [MCP Clients](/guides/troubleshooting/mcp-clients)                              |

## The 60-second triage

<Steps>
  <Step title="Can you list devices?">
    Ask your assistant to call
    [`list_devices`](/api-reference/tools/list-devices). If the call itself
    fails, the problem is [authentication](/guides/troubleshooting/authentication)
    or the [client connection](/guides/troubleshooting/mcp-clients).
  </Step>

  <Step title="Is the device online and unpaused?">
    If `list_devices` works but the device is missing, offline, or `paused`,
    it's a [device problem](/guides/troubleshooting/devices).
  </Step>

  <Step title="What does the task itself say?">
    If devices look healthy, check the task with
    [`phone_task_status`](/api-reference/tools/phone-task-status): its
    `status`, `terminal`, and `error` almost always name the issue - the
    [terminal outcomes table](/guides/concepts/task-lifecycle#terminal-outcomes)
    has the move for each.
  </Step>
</Steps>

## Know your error layer

Errors surface at three layers, and each debugs differently:

* **HTTP** (`401` + `WWW-Authenticate`) - credentials never reached MCP →
  [Authentication](/guides/troubleshooting/authentication)
* **JSON-RPC** (`error.data.reason` like `device_paused`,
  `task_not_found`) - the tool call was rejected → fix the call
* **Task** (`terminal` + task `error` object) - the task ran and ended →
  [Error handling](/guides/best-practices/error-handling)

## Still stuck?

<Card title="Email Support" icon="envelope" href="mailto:support@theagi.company">
  [support@theagi.company](mailto:support@theagi.company) - include the tool call, the full error, and the
  task\_id if you have one
</Card>