Skip to main content
In --json mode, CLI failures are emitted on stdout as: 
{
  "error": {
    "code": "sandbox_not_found",
    "message": "Sandbox not found",
    "hint": "List available sandboxes with `nullspace sandbox list`.",
    "doc_url": "https://docs.your-nullspace-domain/error-codes#sandbox-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

ExitMeaningTypical codes
0Successn/a
1Generic failureunknown, cli_error
2Usage or validation errorinvalid_request, invalid_fields, invalid_response
3Not foundsandbox_not_found, snapshot_not_found, template_not_found, template_build_not_found, template_name_claim_not_found
4Authentication required or invalidmissing_api_key, unauthorized
5Permission deniedpermission_denied, volume_read_only, preview_grant_disabled, preview_proxy_token_disabled, preview_sandbox_disabled
6Quota or rate limitedrate_limit_exceeded, quota_exceeded, volume_limit_exceeded
7Conflictconflict, upload_conflict, volume_busy
8Runtime failuretimeout, exec_failed, exec_timeout

​
invalid_request

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

​
invalid_fields

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

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

​
missing_api_key

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

​
unauthorized

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

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

​
edge_token_expired

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

​
edge_token_invalid

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

​
edge_token_scope_mismatch

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

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

​
preview_grant_revoked

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

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

​
preview_grant_unavailable

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

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

​
preview_proxy_token_expired

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

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

​
preview_proxy_token_revoked

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

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

​
preview_proxy_token_scope_mismatch

The custom preview proxy token is valid but does not match this sandbox, 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.

​
preview_proxy_token_unavailable

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

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

​
preview_service_not_ready

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

​
preview_sandbox_disabled

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

​
edge_runtime_host_unreachable

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

​
sandbox_paused_auto_resume_disabled

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

​
sandbox_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 sandbox startup logs if it repeats.

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

​
edge_auto_resume_timeout

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

​
permission_denied

The authenticated account cannot perform the requested operation.

​
sandbox_not_found

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

​
snapshot_not_found

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

​
template_not_found

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

​
template_build_not_found

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

​
template_name_claim_not_found

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

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

​
quota_exceeded

The request would exceed an account or deployment quota.

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

​
conflict

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

​
timeout

The operation timed out.

​
build_error

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

​
file_upload_error

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

​
unknown

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