Recurse docs / 13
Agent troubleshooting
Give your coding agent the command output, Recurse agent revision, and any printed run ID. Ask it to identify whether the problem happened locally, during packaging or preparation, during the serverless run, or while retrieving state. Each stage has a different recovery path.
You remain responsible for login, purchases, secret values, permissions, and approval before a destructive or billable retry.
Start with this sequence:
- Preserve the run ID or admission reference.
- Do not submit a replacement run yet.
- Identify the failing stage: local setup, packaging, preparation, serverless execution, or retrieval.
- Give the coding agent the command, revision, public error, and relevant non-sensitive inputs.
- Review the proposed fix and likely retry cost before authorizing more work.
Inspect the existing run first
If a run ID exists, ask the coding agent to inspect it before starting another execution:
recurse status RUN_IDA failed observation request does not prove that the run failed or stopped. If the CLI printed an admission reference but no run ID, retain that reference for investigation.
Divide responsibilities clearly
| Coding agent handles | You handle |
|---|---|
| Diagnose manifest, package, tool, input, output, and artifact errors. | Sign in and approve account access. |
| Inspect known run IDs and avoid duplicate submissions. | Decide whether to add credit or increase an allowance. |
| Propose the smallest fix and show how it will be verified. | Enter, rotate, or delete secret values. |
| Retrieve non-sensitive evidence and compare it with acceptance checks. | Approve destructive actions, retries with uncertain cost, and permission changes. |
Installation and login
| Symptom | Next action |
|---|---|
recurse cannot be found | Confirm the SDK executable is on PATH. A terminal and MCP host can have different environments. |
Packaging says uv is required | Install uv and make it available to the process running Recurse. |
| Login cannot open the callback address | Check whether another process is using 127.0.0.1:8765, then retry when available. |
| The system keychain is unavailable | Check access for the user and process running the CLI or MCP bridge. |
authentication_failed | Sign in again with recurse login, then inspect the same run ID rather than submitting a replacement. |
Do not add credentials to project files to work around a login problem.
Manifest, package, and preparation
| Symptom | Ask the coding agent to check |
|---|---|
| A manifest field is rejected | Its exact spelling, type, and allowed value in agent.yaml. |
| A declared file is missing | agent.prompt, tools.source, and runtime.lockfile paths inside the project. |
| A registered tool is rejected | Public function name, annotations, and Google-style docstring. |
| An explicit build system is required | [build-system] and its backend requirements in pyproject.toml. |
| A required file is absent from the package | Source-distribution inclusion rules and archive contents. |
uv.lock changed during packaging | Package the exact lockfile; update it deliberately with uv lock when dependencies change. |
| The archive is too large | Remove unintended caches, environments, datasets, and generated results. |
build_failed | The public diagnostic, dependencies, build configuration, and runtime assets. |
| The model is unsupported or unavailable | agent.model and the current service response. Models are not silently substituted. |
Ask for a clean package check before approving another serverless run.
Run errors
| Public error | Next action |
|---|---|
invalid_inputs | Compare the supplied JSON object with the manifest's inputs schema. |
invalid_agent | Correct the manifest or packaged tool definitions before retrying. |
invalid_output | Compare the final result with outputs, including required and additional properties. |
secret_unavailable | Check secret metadata and the logical binding without exposing the value. |
insufficient_balance | Review Available credit and decide whether to add funds or stop. |
timed_out | Review the work attempted and whether the best feasible result was preserved before the limit. |
cancelled | Inspect available evidence before deciding whether another run is needed. |
artifact_failed | Check where the tools wrote files and preserve the run ID. |
execution_failed or infrastructure_failed | Preserve the public explanation and avoid claiming a more specific cause without evidence. Infrastructure failures have public status: failed and error.code: infrastructure_failed. |
Inspect native run traces for original model and tool events, arguments, results, and error cause chains before deciding whether to retry. Read the existing run through the REST API; trace retrieval does not start another execution. Traces are unredacted and retained for 24 hours after completion, so review the content and share only relevant non-sensitive evidence.
If the run succeeded but its result is poor, treat that as an evaluation problem rather than an execution failure. Use Evaluate and improve.
Lost observation or uncertain cancellation
request_failed means a service request failed. It does not establish that the serverless run stopped. Preserve the run ID in the CLI's YAML output and check its status before trying again.
To request cancellation and inspect the result:
recurse cancel RUN_ID
recurse status RUN_IDThe service-reported terminal state is the evidence that the run ended. Until then, execution and charges may continue. Do not approve a replacement run merely because the local observer stopped.
Artifact and MCP problems
For artifact downloads, treat size or SHA-256 failures as unverified results. A verified retry can replace an existing regular file without losing its previous bytes if the download or verification fails; destination directories and unsafe paths are rejected. Downloads expire 24 hours after completion, while artifact metadata remains visible in recurse status. An available artifacts: [] means no files were produced; artifacts: null means the inventory is pending or unavailable.
For MCP connections, check the recurse executable path, keychain access, deployment ID, stdio transport, and host timeouts. Use a deployment ID rather than a run ID. Local edits require a new deployment and host configuration update.
Preserve evidence for an unresolved failure
Keep:
- The command and SDK version.
- Time of failure and Recurse agent revision.
- Run ID or admission reference.
- Printed state and public error.
- Relevant non-sensitive inputs and artifacts.
Record the SDK version with:
python -c 'from importlib.metadata import version; print(version("recurse-sdk"))'Do not include secret values or private input data in shared diagnostics. When the evidence does not identify the cause, report what is known, what remains uncertain, and what evidence the next diagnostic step should produce.