Skip to main content
Sandbox failures usually look alike from the outside — the run ends without the outcome you wanted. This is how to tell which one you hit.

​
Start with the output

Most misdiagnosis comes from not having the output. Stream it before anything else:
--verbose adds telemetry; --json makes the result parseable rather than prose.

​
Authentication

Symptom: 401 or 403 on any call.
  • Confirm the key is valid and unexpired.
  • Check the header format: Authorization: ApiKey YOUR_API_KEY — not Bearer. This is the most common single mistake, because the rest of the platform uses Bearer.

​
The CLI isn’t there

Symptom: command not found: stateset. The sandbox image must include the CLI. If you’re on a custom or older image, rebuild it or update the runtime image.

​
The write didn’t happen

Symptom: the run reports success, but nothing changed. This is almost always a missing --apply. The CLI is read-only by default, so a write phrased without the flag describes what would happen and exits cleanly. A clean exit with no effect is the signature.
If --apply is present and the write still didn’t land, check guardrail policy for restricted operations, and whether the action exceeded a High-Value Action threshold and is awaiting approval rather than having failed.

​
Timeouts

Symptom: the run ends abruptly at a consistent duration. That consistency is the tell — it’s timeout_seconds, not the workload.
  • Raise the timeout, or reduce the work.
  • Prefer splitting the workflow: a run that dies takes one chunk with it rather than the whole job.
A hung agent bills for the full timeout. Raising it to make a symptom go away can turn a failing run into an expensive one — check whether the agent is stuck in a loop first. See Sandbox costs.

​
Unexpected results, not errors

Symptom: the command succeeds and does the wrong thing. If you’re using the natural-language binary, the phrasing was interpreted differently than you meant. Switch to stateset-direct, which takes explicit commands with no interpretation layer:
For anything an agent runs unattended, this should be the default rather than the fallback.

​
Quick triage

Last modified on August 31, 2026