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

# Agent Sandbox Troubleshooting

> Failure modes when running the agent in a sandbox, and how to tell them apart.

# Agent Sandbox Troubleshooting

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:

```bash theme={null}
curl -X POST https://api.sandbox.stateset.com/api/v1/sandbox/$SANDBOX_ID/execute \
  -H "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "stateset --json --verbose \"show me pending orders\""}'
```

`--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.

```bash theme={null}
# confirm before debugging anything else
{"command": "stateset --version"}
```

## 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.

```bash theme={null}
stateset "ship order #12345 …"            # reports, changes nothing
stateset --apply "ship order #12345 …"    # actually ships
```

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](/stateset-response/responsecx-workflow-studio) 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.

<Warning>
  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](/stateset-icommerce/stateset-icommerce-agent-sandbox-costs).
</Warning>

## 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:

```bash theme={null}
stateset-direct --apply orders ship <order-id> TRACK123
```

For anything an agent runs unattended, this should be the default rather than the fallback.

## Quick triage

| Symptom                      | First check                            |
| ---------------------------- | -------------------------------------- |
| 401 / 403                    | `ApiKey` scheme, not `Bearer`          |
| `command not found`          | CLI present in the image               |
| Success, nothing changed     | Missing `--apply`                      |
| Ends at a fixed duration     | `timeout_seconds`                      |
| Right action, wrong details  | Use `stateset-direct`                  |
| Write blocked with `--apply` | Guardrail policy, or awaiting approval |

## Related

* [Sandbox Runbook](/stateset-icommerce/stateset-icommerce-agent-sandbox-runbook)
* [Sandbox Costs](/stateset-icommerce/stateset-icommerce-agent-sandbox-costs)
* [CLI Safety Model](/stateset-icommerce/stateset-icommerce-cli-safety)