Troubleshooting

Read status and pending actions:

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 before you decide approval, submit a receipt, or request recovery.

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.

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.

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.

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.

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.

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.