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

# Troubleshooting

> Common errors and what to do about them.

Check [status.anonalabs.com](https://status.anonalabs.com) first: if something is down there, it is not your code.

> [accordion] 401 Unauthorized, or the SDK says the API key is invalid
>
> * Check that `ANONA_API_KEY` (or `E2B_API_KEY`, for the stock `e2b` SDK) holds an **Anona Compute** key from the dashboard. E2B keys and Anona Memory keys do not work here.
> * The key may be revoked or expired; see **API keys** in the dashboard.
> * Keys are `ac_` followed by lowercase hex; older keys start with `e2b_` and still work. Check for a stray space or newline when you copy it.

> [accordion] The SDK talks to api.e2b.app instead of Anona
>
> Set `E2B_DOMAIN=compute.anonalabs.com`. Recent SDKs ignore `E2B_API_URL`. Or use `anona_compute.Sandbox` / `@anona-labs/compute-sdk`, which default to the Anona domain.

> [accordion] 404 sandbox not found, but I just created it
>
> * The sandbox may have reached its timeout and been deleted (the default is 300 s from the SDK). Use a longer `timeout`, `set_timeout`, or `lifecycle={"on_timeout": "pause"}`.
> * The key may belong to another organization, or be limited to a list of sandbox IDs. Both look exactly like "not found".

> [accordion] 403 your access cannot open this sandbox
>
> Your key lacks `sandboxes:use` (needed for commands, live view and SSH), or your dashboard role is viewer. Create a key with **Create and use**, or ask an admin for the member role.

> [accordion] 403 this API key lacks the usage:read scope
>
> `anona-compute usage`, the MCP `get_usage` tool and `GET /v1/usage` need a key with `usage:read` (the **Read only** and **Full access** presets have it); billing needs `billing:read` (**Full access**). Create a new key; existing keys keep their scopes.

> [accordion] 403 only organization owners and admins ... may change network settings and vault secrets
>
> Team egress settings and the credential vault are changed by dashboard owners and admins, or by an [unrestricted API key](/docs/guides/ci.md#create-a-key-for-ci). Any role, and any key without a sandbox list, can read them.

> [accordion] 403 vault secret ... is not bound to ... for this sandbox
>
> The rule needs a new binding, and you may not make one. A binding belongs to one sandbox, so this happens even when another sandbox has the same rule. Create the sandbox as an organization owner or admin, or with an API key that has the `vault:bind` scope (a custom key; no preset has it). Or ask an owner to put the rule in the team egress settings, which every sandbox can use. See [Bindings and who can make them](/docs/concepts/networking.md#bindings-and-who-can-make-them).

> [accordion] 400 no vault secret named ... is bound to this sandbox / store it in the credential vault first
>
> Store the secret under exactly the name the rule uses (`${vault.<name>}`), then create the sandbox again. Either the dashboard's **Credential vault** page, or:
>
> ```bash store_secret.sh
> anona-compute vault create github_token --host api.github.com --value-file token.txt
> anona-compute vault list
> ```

> [accordion] 403 vault secret ... may not be sent to ...
>
> Every secret records the hosts it may be sent to, and a rule aiming it anywhere else is refused. Without that list, anyone who can write an egress rule could point your credential at a server they control. Check the list with `anona-compute vault list` and replace it with `anona-compute vault allowed-hosts <name> --host api.github.com`. A `*.` entry does not cover the domain itself: `*.github.com` does not cover `github.com`.
>
> A secret stored before allowed hosts existed has none recorded and cannot be used until you set one.

> [accordion] 502 on a request that should carry a vault header
>
> The egress proxy could not resolve the secret, so it **refused the request instead of sending it without the credential**. That is deliberate: a request that silently lost its `Authorization` header would reach the upstream unauthenticated.
>
> The handshake to the host still succeeds, so this looks like the upstream failing rather than the policy. Causes, commonest first:
>
> * The secret was deleted, or the binding was revoked (`anona-compute vault list` shows neither).
> * The allowed-hosts list was narrowed and no longer covers this host.
> * The organization is suspended for billing or abuse; every resolution is refused while it is.
>
> If none of those apply, the request is being refused on the host rather than by the policy, and it needs an operator. Open a ticket with the sandbox ID and the time.

> [accordion] Certificate error on a host with a vault rule
>
> For a host with a vault rule, the egress proxy presents a certificate from its own certificate authority (see [How it works](/docs/concepts/networking.md#how-it-works)). Sandboxes trust it through `/etc/ssl/certs/ca-certificates.crt`, so curl, Python's default SSL context and Node work. A client with its own certificate store does not: Python with certifi's bundle passed explicitly, a Java keystore, or a pinned certificate.
>
> Point the client at the system bundle. In Python, drop `cafile=certifi.where()` or pass `/etc/ssl/certs/ca-certificates.crt` instead; for Java, import that file into the keystore the client uses. A certificate pinned for that host cannot match, so remove the pin.

> [accordion] 429 concurrent sandbox limit reached, or concurrent vCPU limit reached
>
> Delete sandboxes you no longer need (`anona-compute list`, then `anona-compute delete`), or pause them: paused sandboxes do not count as running. For the vCPU limit, a smaller size also helps: on Free, `size: "small"` is 1 vCPU, and a sandbox created without a size from `base` is 2. The error's `limit_name`, `limit` and `current` say which limit and how much is in use. See [limits](/docs/concepts/limits.md).

> [accordion] 403 plan\_limit\_exceeded
>
> A plan limit that only you can clear: an API key, template or paused sandbox beyond your plan's count, template storage full, a size above your plan's largest, or on Free the month's included vCPU-hours or egress used up (`included_vcpu_hours`, `included_egress_gb`; it resets on the first of the month). `limit_name` says which. Delete something you no longer need, or upgrade the plan. See [limits](/docs/concepts/limits.md).

> [accordion] 400 timeout -1 (no limit) is not available
>
> Anona has set a maximum lifetime on your team; no plan has one. Use a timeout up to that maximum, or open a ticket to have it removed.

> [accordion] 400 volumeMounts / iam / autoPauseMemory=false are not supported
>
> These E2B features are not available on Anona Compute; remove them from the create call. See [Migrate from E2B](/docs/migrate-from-e2b.md#not-available-yet).

> [accordion] 400 on create with network.allow\_out
>
> Host names in `allow_out` need public egress off: add `deny_out: ["0.0.0.0/0"]`. Destinations in private or metadata ranges, and names that resolve into them, are always refused. Wildcard names such as `*.example.com` are not supported yet: name each host. See [Networking](/docs/concepts/networking.md).

> [accordion] 503 with Retry-After on create
>
> The platform is not ready to serve the create yet: with `sandbox_capacity_unavailable`, every host is full and another is starting, which takes a few minutes. The CLI waits up to `--capacity-wait` (10 minutes). The stock E2B SDK retries for about a minute; the Anona SDK extras, from 0.3.0, wait up to 10 minutes ([Python](/docs/sdk/python.md#waiting-for-capacity), [TypeScript](/docs/sdk/typescript.md#waiting-for-capacity)). If you call the API yourself, wait `Retry-After` seconds and retry while the response says `Should-Retry: true`.

> [accordion] 409 when opening a sandbox URL
>
> The sandbox is paused, for example by its idle timer. Resume it with `Sandbox.connect(id)` or `anona-compute resume <id>`.

> [accordion] ssh: Permission denied (publickey)
>
> The certificate is older than 10 minutes, or was minted for another sandbox. Run `anona-compute ssh <id>` again, or refresh the block with `anona-compute ssh <id> --print-config`.

> [accordion] The live view says the token expired or closes at once
>
> Tokens last at most 10 minutes. Answer the embed's `token-request` message with a fresh token ([Live view](/docs/guides/live-view.md#keep-a-long-session-alive)). After `revoke_all`, mint new tokens.

> [accordion] A template build fails with EXPOSE 49983 or an unpinned FROM
>
> Port 49983 belongs to the Anona runtime (`envd`), so a template cannot expose it. Every `FROM` is pinned by digest at build time; a tag that cannot be resolved fails the build. See [Templates](/docs/concepts/templates.md#build-your-own).

> [accordion] anona-compute keys / limits / push / recover say not available
>
> These commands exist in the CLI ahead of their server side. See the [CLI overview](/docs/cli/overview.md) for what is coming.

## Get more detail

* `anona-compute -v …` prints verbose detail on stderr.
* Every API error body has `code`, `message` and `requestId`, and often `error_code`. Include the `requestId` when you contact support.


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