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

# Troubleshooting agent sandboxes

> What each agent sandbox error means, from access and capacity to resume, billing, attestation, and the screen lock, and what to do next.

Every message the CLI prints has a next step. The tables below group them by
where they happen.

## Access

Until your account is granted sandboxes, the sandbox API answers as if it did
not exist. The CLI says:

```text theme={null}
the plane found nothing for this account (404 not_found: …): agent sandboxes may be off on https://api-sandbox.darkbloom.dev/, or the account may not be allowlisted for them. They are by invitation: ask your Darkbloom contact for access, …
```

Send the Account ID the console shows under **Settings** and the platforms you
need to your Darkbloom contact. A grant of one platform does not cover the
other.

## Create and placement

| You see | What it means | What to do |
| - | - | - |
| `no Mac has room for a c4-m8 linux_arm64 sandbox right now, so sbx-… did not start (failed: no_capacity)` | The fleet had no room for that size. Nothing was charged. | Retry in a few minutes, or choose a smaller size (`sizes`). |
| `create` waits a few seconds and goes on after `the request did not finish` or a lost connection | Its answer was lost. `create` finds the sandbox the service made by the nonce it sent, or sends the same create again (twice at most). | Nothing. If it still fails it names the nonce: `list` shows the sandbox if the service made it; `delete` it if you do not need it. |
| `create` says `sbx-… waits for a Mac: reading it until it is placed` | Darkbloom accepted the sandbox and is still finding it a Mac. `create` waits, because it records the image the sandbox boots, which is known once it has a Mac. | Nothing: it goes on by itself, for up to 5 minutes. If you interrupt it (Ctrl-C), the sandbox is left without a record on this computer: delete it with the command that line names, `darkbloom-sandbox-cli delete sbx-…`. |
| `sbx-… was created but no Mac took it within 5 min; deleted sbx-…` | No Mac took the sandbox while `create` waited, so `create` deleted it (it had no record yet, so nothing was using it). | Create it again later (with a new `--nonce` if you passed one), or with another size (`darkbloom-sandbox-cli sizes`). |
| `sbx-… was created but …: delete it with darkbloom-sandbox-cli delete sbx-…` | `create` could not follow the sandbox to its Mac, or could not delete it once it gave up (the service did not answer, or refused), so the sandbox is left without a record on this computer. | Run that command once the service answers again. |
| `the plane answered a read of sbx-… with …: refused, nothing was recorded, and sbx-… was not deleted` | While `create` waited, the service answered with another sandbox than the one this create made. `create` trusts no such answer: it records nothing and deletes nothing. | Check the sandbox with the `status … --json` command the message names (its `nonce` is this create's if it is yours); if it is yours, delete it with the `delete` command the message names. Tell your Darkbloom contact. |
| `sbx-… was created but is gone` | The sandbox was deleted while `create` waited (from another client, or by Darkbloom). | Nothing to clean up: create another if you need one. |
| `sbx-… stopped … before this create recorded it`, or `was deleted … before this create recorded it` | Another client (the console, another CLI) stopped or deleted the sandbox while `create` waited, so `create` failed and recorded nothing. | A stopped one cannot be resumed from this computer: delete it with the command the message names, and create another. |
| `…: this client has a record of sbx-…, so create does not delete it`, or `… while this create waited for its placement …: this client's record of sbx-… is left as it was` | A create repeated with `--nonce` found its sandbox, which this computer already recorded, still waiting for a Mac (or stopped or deleted meanwhile). `create` never deletes a sandbox it has a record of. | `darkbloom-sandbox-cli status sbx-…` shows it. Run the same create again later, or `delete` the sandbox if you do not need it. |

## Resume

| You see | What it means | What to do |
| - | - | - |
| `the Mac that holds sbx-…'s workspace has no room for it right now … (409 no_capacity)` | A resume runs only on its workspace's Mac, which is busy. | Retry `resume` in a few minutes. |
| `the Mac that holds this sandbox's workspace has just restarted …` (or `… is downloading the image this sandbox boots from …`, `… is reconnecting to Darkbloom …`) `… nothing changed and the sandbox is still stopped` | That Mac is not busy, only getting ready: after a Darkbloom update or a restart it takes sandboxes again within a minute or two. Nothing was charged and the retry costs nothing. | Run the same `resume` again in a minute (a few seconds for `reconnecting`). |
| `the Mac that holds sbx-…'s workspace is offline or not taking sandboxes … (409 host_unavailable)` | That Mac is away; the workspace is kept on it. | Retry `resume` once it is back; `status` shows since when it is offline and until when the workspace is kept. |
| `the Mac that held sbx-…'s workspace was removed, so sbx-… cannot resume … (409 host_removed)`, or `status` says `its Mac was removed` | That Mac left the fleet for good; the sandbox no longer counts toward your storage. | `delete` it; no retry will resume it. |
| `sbx-… was not resumed: the plane boots … from image … now, … (409 upgrade_required)` | Darkbloom moved the image pin. | See [image upgrades](https://docs.darkbloom.dev/sandboxes/lifecycle.md#image-upgrades). |
| `sbx-… is already running (ready), so there is nothing to resume` (or `already starting`, `still stopping`) (`409 conflict`) | `resume` boots only a stopped sandbox; nothing changed. | Use it (`ssh`), or wait until `status` says stopped and resume again. |
| `a resume of sbx-… is saved and its outcome is not known yet` | An earlier `resume` lost the service's answer, or its workspace's Mac had no room or was offline (or, with an older CLI, `resume` was run on a running sandbox). | Run `darkbloom-sandbox-cli resume sbx-…`: it sends the saved resume again, which settles it. If it still says so while the sandbox runs, stop the sandbox, then resume it. |

## Billing

| You see | What it means | What to do |
| - | - | - |
| `… the account's balance could not cover the hold for its boot (failed: unfunded)` | Your balance cannot hold an hour of the size. | Add funds, then run the command again. |
| `: Darkbloom's billing could not charge for it (billing_lapsed), a problem on Darkbloom's side, not the account's` (or `unbillable`) | Darkbloom's side. | Resume it in a few minutes (a create that did not start, `failed: unbillable`: run the create again); the workspace is kept. |

## Stops

| You see | What it means | What to do |
| - | - | - |
| stopped `after 15 idle minutes with no client attached and no traffic` | The idle limit. | See [idle limit, keepalive, and maximum](https://docs.darkbloom.dev/sandboxes/lifecycle.md#idle-limit-keepalive-and-maximum): keepalive, or keep a client attached. |
| stopped `at its maximum of 240 minutes per boot` | The maximum. | `resume`; next time `--max-minutes` or `extend`. |
| `: its Mac went offline while it ran` (`host_lost`) | The Mac disappeared; billing stopped then. | `resume` when the Mac is back (persistent sandboxes), unless `status` says `its Mac was removed`: then `delete` it. |

## Attestation

| You see | What it means | What to do |
| - | - | - |
| `: its boot failed attestation` (`verification_failed`) | The service could not verify the boot's statement, so the boot never became ready (and was not billed). | Create a new sandbox; tell your Darkbloom contact. |
| `ssh`, `vnc`, or `attest` refuses to connect because verification failed, or the build is revoked | Your CLI could not prove the boot runs a Darkbloom-qualified build on a genuine Mac (or Darkbloom revoked that build). | Do not work around it (no other client, no unattested key): delete the sandbox, create a new one, and report it. This check is what makes the guarantees in [security](https://docs.darkbloom.dev/sandboxes/security.md) hold. |

## Limits and the desktop

| You see | What it means | What to do |
| - | - | - |
| `409 limit_reached`, `429 rate_limited` | A per-account limit or the start rate. | See [limits](https://docs.darkbloom.dev/sandboxes/limits-and-billing.md#limits). |
| `sbx-…'s screen is locked. …`, or a macOS desktop that shows only the wallpaper and takes no input | The desktop is locked: macOS locks it after 20 minutes without input unless a CLI connection turned that off earlier in the boot (or something in the sandbox locked it). | `stop` and `resume` it, then connect within 20 minutes. See [the desktop (VNC)](https://docs.darkbloom.dev/sandboxes/create-and-connect.md#the-desktop-vnc). |

A host outside the egress policy fails inside the guest with `curl: (56)
CONNECT tunnel failed, response 403`; see [network and
egress](https://docs.darkbloom.dev/sandboxes/create-and-connect.md#network-and-egress).


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