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

# Error Codes

> Stable CLI exit codes and JSON error-code anchors.

In `--json` mode, CLI failures are emitted on stdout as:

```json theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
{
  "error": {
    "code": "machine_not_found",
    "message": "Machine not found",
    "hint": "List available machines with `nullspace machine list`.",
    "doc_url": "https://docs.your-nullspace-domain/error-codes#machine-not-found",
    "request_id": null,
    "retryable": null,
    "suggested_action": null
  }
}
```

Preview and auto-resume errors may include `retryable`, `suggested_action`,
and request-specific details. Surface those fields in SDK, CLI, console, and
automation logs after redacting bearer credentials.

## Exit Codes

| Exit | Meaning                            | Typical codes                                                                                                                 |
| ---: | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|    0 | Success                            | n/a                                                                                                                           |
|    1 | Generic failure                    | `unknown`, `cli_error`                                                                                                        |
|    2 | Usage or validation error          | `invalid_request`, `invalid_fields`, `invalid_response`                                                                       |
|    3 | Not found                          | `machine_not_found`, `snapshot_not_found`, `template_not_found`, `template_build_not_found`, `template_name_claim_not_found`  |
|    4 | Authentication required or invalid | `missing_api_key`, `unauthorized`                                                                                             |
|    5 | Permission denied                  | `permission_denied`, `volume_read_only`, `preview_grant_disabled`, `preview_proxy_token_disabled`, `preview_machine_disabled` |
|    6 | Quota or rate limited              | `rate_limit_exceeded`, `quota_exceeded`, `volume_limit_exceeded`                                                              |
|    7 | Conflict                           | `conflict`, `upload_conflict`, `volume_busy`                                                                                  |
|    8 | Runtime failure                    | `timeout`, `exec_failed`, `exec_timeout`                                                                                      |

<a id="invalid-request" />

## invalid\_request

The command or API request failed validation. Inspect `message` and rerun the
command with `--help`.

<a id="invalid-fields" />

## invalid\_fields

A `--fields` value names a field that the endpoint does not support. Remove or
rename the field and retry.

<a id="invalid-response" />

## invalid\_response

The SDK or CLI received a response shape that does not match the expected
contract. Retry once, then report the response details if it repeats.

<a id="missing-api-key" />

## missing\_api\_key

No API key was provided. Export `NULLSPACE_API_KEY`, pass `api_key=...`, or run
`nullspace auth login`.

<a id="unauthorized" />

## unauthorized

The configured API key was rejected. Check the key, target API URL, and account
access.

<a id="edge-token-missing" />

## edge\_token\_missing

A direct public preview request did not include a signed `edge_token` query
credential or a valid Nullspace preview continuation cookie. Request a fresh
signed preview URL and use the full returned URL.

<a id="edge-token-expired" />

## edge\_token\_expired

The signed direct preview credential or its durable grant expired. Request a
fresh preview URL.

<a id="edge-token-invalid" />

## edge\_token\_invalid

The direct preview credential could not be verified. Request a fresh preview URL
for the same machine, port, and HTTP/WebSocket transport.

<a id="edge-token-scope-mismatch" />

## edge\_token\_scope\_mismatch

The direct preview credential is valid but does not match this machine, port, or
HTTP/WebSocket transport. Request a fresh preview URL for the current route.

<a id="preview-grant-invalid" />

## preview\_grant\_invalid

The durable preview grant referenced by a direct preview credential is invalid
or does not match the edge request. Request a fresh preview URL.

<a id="preview-grant-revoked" />

## preview\_grant\_revoked

The durable preview grant was revoked. Request a fresh preview URL.

<a id="preview-grant-disabled" />

## preview\_grant\_disabled

An operator temporarily disabled this durable preview grant. Request a different
preview route or ask an operator to re-enable the grant before retrying.

<a id="preview-grant-unavailable" />

## preview\_grant\_unavailable

Edge could not validate the durable preview grant and failed closed. Retry after
the service recovers.

<a id="preview-proxy-token-missing" />

## preview\_proxy\_token\_missing

A custom preview proxy request indicated header transport but omitted
`x-nullspace-preview-proxy-token`. Create a preview proxy target and forward the
returned token header.

<a id="preview-proxy-token-expired" />

## preview\_proxy\_token\_expired

The custom preview proxy token or its durable grant expired. Create a fresh
proxy target.

<a id="preview-proxy-token-invalid" />

## preview\_proxy\_token\_invalid

The custom preview proxy token could not be verified or does not reference a
valid header-transport grant. Create a fresh preview proxy target.

<a id="preview-proxy-token-revoked" />

## preview\_proxy\_token\_revoked

The custom preview proxy token's durable grant was revoked. Create a fresh proxy
target.

<a id="preview-proxy-token-disabled" />

## preview\_proxy\_token\_disabled

An operator temporarily disabled the durable grant behind this preview proxy
token. Ask an operator to re-enable the grant or create another approved route.

<a id="preview-proxy-token-scope-mismatch" />

## preview\_proxy\_token\_scope\_mismatch

The custom preview proxy token is valid but does not match this machine, port,
HTTP/WebSocket transport, or was mixed with direct query/cookie credentials.
Create a fresh preview proxy target for the current route and do not mix direct
query/cookie credentials with header transport.

<a id="preview-proxy-token-unavailable" />

## preview\_proxy\_token\_unavailable

Edge could not validate the custom preview proxy token's durable grant and
failed closed. Retry after the service recovers.

<a id="unsupported-preview-port" />

## unsupported\_preview\_port

The requested preview port is not supported by generic browser preview APIs. Use
an application port in `1`-`65535` except `22` and `5900`-`5999`.

<a id="preview-service-not-ready" />

## preview\_service\_not\_ready

Preview routing exists, but the service inside the machine was not listening on
the requested port before the readiness timeout. Confirm the process is running
and binding to `0.0.0.0`.

<a id="preview-machine-disabled" />

## preview\_machine\_disabled

An operator temporarily disabled all preview traffic for this machine. Ask an
operator to re-enable machine preview traffic before retrying.

<a id="edge-runtime-host-unreachable" />

## edge\_runtime\_host\_unreachable

Edge resolved the machine route but could not reach the assigned runtime host
proxy. Check readiness with `machine.wait_for_preview(port)` or
`nullspace machine url <id> <port> --wait`, then retry.

<a id="machine-paused-auto-resume-disabled" />

## machine\_paused\_auto\_resume\_disabled

The preview URL points at a paused machine that is not eligible for traffic
triggered auto-resume. Resume it manually or recreate it with
`on_timeout="pause", auto_resume=True`.

<a id="machine-auto-resume-timeout" />

## machine\_auto\_resume\_timeout

The control plane began auto-resume but it did not complete within the edge wait
window. Respect `Retry-After`, retry, and inspect runtime capacity or machine
startup logs if it repeats.

<a id="edge-auto-resume-control-plane-unreachable" />

## edge\_auto\_resume\_control\_plane\_unreachable

Edge could not reach the control-plane auto-resume endpoint. Respect
`Retry-After` and retry after the control plane recovers.

<a id="edge-auto-resume-timeout" />

## edge\_auto\_resume\_timeout

Edge timed out waiting for the control-plane auto-resume request. Respect
`Retry-After` and retry.

<a id="permission-denied" />

## permission\_denied

The authenticated account cannot perform the requested operation.

<a id="machine-not-found" />

## machine\_not\_found

The machine ID does not exist or is not visible to the authenticated account.

<a id="snapshot-not-found" />

## snapshot\_not\_found

The snapshot ID does not exist or is not visible to the authenticated account.

<a id="template-not-found" />

## template\_not\_found

The template ID or ref does not exist or is not visible to the authenticated
account.

<a id="template-build-not-found" />

## template\_build\_not\_found

The template build ID does not exist or is not visible to the authenticated
account.

<a id="template-name-claim-not-found" />

## template\_name\_claim\_not\_found

The template name claim does not exist, is expired, or is not visible to the
authenticated account.

<a id="rate-limit-exceeded" />

## rate\_limit\_exceeded

The request hit a rate limit. Respect `retryable`, `Retry-After`, and any retry
timing supplied by the API or edge response before retrying.

<a id="quota-exceeded" />

## quota\_exceeded

The request would exceed an account or deployment quota.

<a id="warm-pool-unavailable" />

## warm\_pool\_unavailable

A `require` template warm-pool checkout could not claim matching ready
inventory, or the create request shape is not poolable. Use `prefer` when cold
fallback is acceptable, wait for the pool to become ready, or remove
create-time inputs that are not part of the poolable startup contract.

<a id="conflict" />

## conflict

The requested mutation conflicts with current resource state. Refresh the
resource and retry with the latest state.

<a id="timeout" />

## timeout

The operation timed out.

<a id="build-error" />

## build\_error

A template build failed. Inspect `error_detail` for the build phase, failed
step, retryability, and suggested action.

<a id="file-upload-error" />

## file\_upload\_error

A file or directory upload failed. Inspect `error_detail` for retry and resume
metadata.

<a id="unknown" />

## unknown

The failure did not map to a more specific stable code.