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

# bead sandbox troubleshooting

> Start bead sandbox troubleshooting with credentials, admission, machine readiness, command errors, and uncertain results.

For bead sandbox troubleshooting, start with the machine state and the structured error. Keep the machine or execution identifier so you can inspect the same work.

```bash theme={null}
bead inspect MACHINE_ID
bead limits
bead balance
```

## A credential is rejected

For HTTP 401, check expiry, the API origin, and the selected credential file. `BEAD_API_KEY` overrides a saved file. Private credential files must have mode `0600`.

For a permission refusal, use a credential with the required scope. Ownership and billing administration require admin authority. See [Agent authentication](https://docs.bead.run/platform/agent-auth.md).

## A machine cannot start

For HTTP 429, read the named limit, `maximum`, `usage`, `reset_at`, and `next_action`. Honor `Retry-After` when present. Resource limits may require releasing capacity rather than waiting for a timer.

`free_capacity_full` means trial capacity cannot admit the request. Follow its retry guidance or add credit for paid admission. See [Limits and availability](https://docs.bead.run/platform/limits.md).

For HTTP 402 `insufficient_credit`, inspect reservations and funded deadlines. Adding credit alone does not extend a temporary machine's timeout. See [Credit and payment problems](https://docs.bead.run/help/credit.md).

## A machine does not answer

Inspect readiness before sending commands. `machine_unavailable` is retryable and carries retry guidance. `machine_lost` is terminal and marks the response `retryable: false`; repeatedly reconnecting cannot restore that machine.

Check [Service status](https://docs.bead.run/help/status.md), then [Connection problems](https://docs.bead.run/help/connections.md) for forwarding or desktop-specific failures.

## A command failed

Read the command's exit code, stdout, and stderr. A command can fail even when HTTP transport succeeds. Connect terminal errors can arrive with HTTP 200, so inspect the protocol result as well.

CLI guest errors preserve bounded status and response evidence. `truncated` means part of the response was omitted; `incomplete` means the response could not be fully read.

## The reply was lost

Do not blindly repeat a command that may have run. Recover output using its execution or result identifier. For worktrees, use `bead worktree status --execution ID`; see [Worktree problems](https://docs.bead.run/help/worktrees.md).

An idempotency mismatch means the request changed under the same key. Keep the original request and inspect its outcome before starting different work. See [Command output and recovery](https://docs.bead.run/run-work/output.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.