> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Troubleshooting

Troubleshooting rules on this page:

1. Start from the failed operation, the error's `code`, and returned IDs (project, agent, session, run, input receipt). A failed read is not a reason to submit the task again.
2. Status codes: 401/403 access; 404 wrong project or ID, or no trajectory; 402 `insufficient_credits`; 409 `idempotency_conflict`, `agent_disabled`, `release_unavailable`; 422 validation; 429 `agent_capacity_full` + `Retry-After`; 503 with `agent_unavailable`, `turn_delivery_pending`, `execution_storage_unavailable`, `trajectory_storage_unavailable` + `Retry-After` (nothing new ran; resend the same request); 503 creating an agent or evaluation means the capability is not enabled or available. Other 5xx: retry reads with bounded backoff; reconcile mutations.
3. Waiting run: `client.runs.get(project, run_id)` and `client.runs.pending_actions(project, run_id)`; resolve the specific action.
4. Failed run: read `error.code` and `error.recoverable`; if recoverable, `client.runs.retry(project, run_id)` creates a new run with a new run ID.
5. Timeouts and disconnected streams do not cancel execution; read status and resume events from the last processed cursor.
6. Sessions pin their release; start a new session to use a newer release.
7. Current SDK: `runs.events(...)` for JSON pages, `runs.stream_events(...)` for an iterator; do not pass `stream="false"` to Python `events`.

Start with the operation that failed, the error's `code`, and the identifiers the service returned. Keep project, agent, session, run, and input receipt IDs where available.

> **Warning**
>
> A failed read is not a reason to submit the task again.

## Requests fail before work starts

| Symptom                               | Check                                                                                                                                | Next step                                                                                                                                        |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401` or `403`                        | Credential, project ownership, and operation permissions                                                                             | Follow [Authentication](/get-started/authentication); retry only after correcting access.                                                        |
| `404`                                 | Project and resource IDs; whether the caller can access them                                                                         | Read the resource from the correct project. For trajectories, also consider evidence availability.                                               |
| `402`                                 | The body's `code` is `insufficient_credits`                                                                                          | Check your plan, credits and the agent's spending cap in Billing.                                                                                |
| `409`                                 | The body's `code`, such as `idempotency_conflict`, `agent_disabled` or `release_unavailable`                                         | Act on the code; see [Refused requests](/run/runs-and-tool-requests#refused-requests). Reuse idempotency keys only for identical requests.       |
| `422`                                 | Required fields, allowed values, or definition/schema validation                                                                     | Correct the request using its API Reference schema and error details.                                                                            |
| `429`                                 | The body's `code`, such as `agent_capacity_full`, and `Retry-After`                                                                  | Wait for `Retry-After`, then send the same request with the same idempotency key. Avoid retry bursts.                                            |
| `503` with a `code`                   | `agent_unavailable`, `turn_delivery_pending`, `execution_storage_unavailable` or `trajectory_storage_unavailable`, and `Retry-After` | Nothing new ran. Wait for `Retry-After`, then send the same request again. See [Refused requests](/run/runs-and-tool-requests#refused-requests). |
| `503` creating an agent or evaluation | Whether that capability is enabled and available                                                                                     | Contact support if availability does not recover; changing IDs does not enable it.                                                               |

Other `5xx` responses indicate a service failure. Retry reads with bounded backoff. For mutations, reconcile any retained resource or receipt before you repeat the action.

## Runs and sessions

#### A run is waiting instead of answering

Read status and pending actions:

```python
current = client.runs.get(project, run_id)
actions = client.runs.pending_actions(project, run_id)
print(current.status)
```

**Cause:** a tool may need approval, an application-owned result, renewed connection access, or an available local executor.

**Fix:** resolve the specific action. Polling faster does not execute a tool. Read [Runs and tool requests](/run/runs-and-tool-requests) before you decide approval, submit a receipt, or request recovery.

#### A run failed

Read the run's `error`. Its `code` says what happened. `recoverable` says whether `client.runs.retry(project, run_id)` can run the turn again.

* A retry is a new run. Follow the run ID it returns.
* When `recoverable` is false, follow `error.message`, for example by adding credits or starting a new session.

See [Handle failures](/run/runs-and-tool-requests#handle-failures).

#### The HTTP request or event stream ended

**Cause:** a timeout or disconnected stream. It does not cancel execution. An event stream can also close while idle.

**Fix:**

* If you have a run ID, read its status and resume events from the last processed cursor.
* If a mutation lost its response, use its retained idempotency key and original payload to reconcile the submission, when that operation supports idempotency.
* Check status before you treat a disconnect as completion.
* Deduplicate replayed events by identity.
* Do not start another run just to reconnect.

#### There is a run but no trajectory

Status, retained evidence, and usage measurements are distinct. A run may be admitted or complete while evidence is partial or unavailable.

For an authorized run, a trajectory `404` can mean no retained snapshot exists. It can also mean a missing or inaccessible run. A service error means the read failed.

**Fix:** check the selected project and the managed history in **Conversations**. Managed runs and submitted traces have separate views. Do not upload a managed run again to repair a failed evidence read. See [Trace ingestion](/improve/trace-ingestion).

#### New instructions are not used in an existing session

**Cause:** sessions pin their release. A promoted release does not silently replace an existing session's definition.

**Fix:** inspect the agent's active release, then start a new session to use it. See [Agents and releases](/build/agents-and-releases).

## Setup and clients

#### The quickstart agent already exists

List agents and inspect `support-quickstart`. Reuse it if it is the agent you intended to run. Choose a new slug only when you want a separate agent.

Re-running the entire tutorial without this check can conflict at creation or start an additional task.

#### The SDK rejects an example argument

Check the installed client version and its method reference. Current clients use `runs.events(...)` for JSON pages and `runs.stream_events(...)` for an event iterator.

* Do not pass `stream="false"` to the current Python `events` method.
* An older client may need a package upgrade (`uv add --upgrade sikaru_api` or `npm install @sikaru/sdk@latest`) to use newer endpoints.

## Ask for help

Send [support](/help/support) the operation, client version, approximate time and time zone, relevant IDs, HTTP status, and a minimal reproduction. Share customer content only through an appropriate private support channel. Remove keys, authorization headers, and sensitive payloads from logs before you share them.

## Next steps

#### [Runs and tool requests](/run/runs-and-tool-requests)

Refused requests, waiting actions, and failure handling.

#### [Support](/help/support)

Contact Sikaru or report a client issue.