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

# Troubleshooting

> Resolve common run, credential, worker, and tool configuration problems.

## A run is rejected

* Confirm `AIR_BASE_URL` is the API URL, not the console URL.
* Confirm the app key and agent belong to the same project.
* Use the agent API ID—not its display name—as `agent_id`.
* Confirm the agent has an active version and usable model access.

`AirProtocolError.status_code` contains the HTTP status. `401` usually means the
key is missing, invalid, or revoked. `403` usually means it has the wrong scope
or project.

## A tool stays awaiting approval

Worker registration only discovers capability. A project owner must open
**Tools**, review the manifest, and select **Enable tool**. Then add the enabled
tool to a new agent version and activate that version.

## A worker receives no tasks

* Confirm the worker key and agent belong to the same project.
* Confirm the tool is enabled and allowed by the active agent version.
* Confirm the model requested the tool in the run trace.
* Confirm the worker remains running after registration.
* Check outbound HTTPS access to the AIR API.

## A tool fails

Every tool must return a dictionary. Inspect the worker log for the original
exception and the run trace for the recorded failure. Validate arguments,
tenant access, downstream credentials, and timeouts.

## Waiting timed out

`RunTimeoutError` only means the local wait deadline expired. The server-side
run may still be active.

```python theme={null}
try:
    result = await client.runs.wait(run.id, timeout=30)
except RunTimeoutError:
    current = await client.runs.get(run.id)
```

Read the run again, inspect its trace, or cancel it explicitly.