# Errors

Every error the Cua SDK raises: its variant, message, cause and fix.

> Agent discovery: use [the Cua documentation index](https://cua.ai/docs/llms.txt) to find related pages and their Markdown URLs.







Every fallible call raises (throws) one error type, `CuaError`. Its variant says what went wrong; its message carries the detail; its doc URL links to the variant's entry on this page (`https://cua.ai/docs/cua-sdk/reference/errors#<variant in lower case>`).

The Python high-level API raises its own exceptions (`SpacesdNotAvailable`, `PoolSpecMismatch`, ...), listed on [Python: configuration and errors](</docs/cua-sdk/reference/python/configuration#errors>). cua-spacesd answers RPCs with a `google.rpc.Status` carrying [`ErrorInfo`](</docs/cua-sdk/reference/protocol/env-common#errorinfo>); the SDK maps it to the variants below.

| Language | Type | A variant | Doc URL |
| --- | --- | --- | --- |
| Python | `cua.CuaError` | `cua.CuaError.InvalidArgument` | `e.doc_url` |
| TypeScript | `CuaError` | `CuaError.InvalidArgument`, tested with `CuaError.InvalidArgument.instanceOf(e)` | `e.docUrl`, `cuaErrorDocUrl(e)` |
| Swift | `CuaError` | `CuaError.InvalidArgument(message:)` | `e.docUrl` |
| Kotlin | `CuaException` | `CuaException.InvalidArgument` | `e.docUrl` |
| Rust | `cua_sdk::CuaError` | `CuaError::InvalidArgument(String)` | `e.doc_url()` |

**Example**






**Python**



```python test="docs" id="cua-error-py" session="cua-error-py" prelude="spacesd,spacesd-vars"
import asyncio

import cua

async def main():
    sb = await cua.embedded().sandboxes().connect_url(URL, "wrong-token", None)
    try:
        await sb.spacesd(5000)
    except cua.CuaError.Unauthenticated as e:  # one variant
        print("rejected:", e)
    except cua.CuaError as e:  # any other
        raise

asyncio.run(main())
```






**TypeScript**



```ts test="docs" id="cua-error-ts" prelude="spacesd,spacesd-vars"
import { CuaError, embedded } from '@trycua/cua';

const sb = await embedded().sandboxes().connectUrl(URL, 'wrong-token', undefined);
try {
  await sb.spacesd(5000);
} catch (e) {
  if (!CuaError.Unauthenticated.instanceOf(e)) throw e;
  console.log('rejected:', e.message);
}
```






**Swift**



```swift test="swift" id="cua-error-swift"
import Cua

let sb = try await Cua.embedded().sandboxes().connectUrl(url: "http://10.0.0.5:3211", token: "wrong-token", name: nil)
do {
    _ = try await sb.spacesd(probeTimeoutMs: 5000)
} catch CuaError.Unauthenticated(let message) {  // one case; any other CuaError propagates
    print("rejected:", message)
}
```






**Kotlin**



```kotlin test="kotlin" id="cua-error-kt"
import ai.cua.sdk.Cua
import ai.cua.sdk.CuaConfig
import ai.cua.sdk.CuaException

val sb = Cua.embedded(CuaConfig()).sandboxes().connectUrl("http://10.0.0.5:3211", "wrong-token", null)
try {
    sb.spacesd(5000u)
} catch (e: CuaException.Unauthenticated) { // one subclass; any other CuaException propagates
    println("rejected: ${e.message}")
}
```






## Variants

| Variant | Message | Cause |
| --- | --- | --- |
| [`InvalidArgument`](#invalidargument) | `invalid argument: <detail>` | Bad input. |
| [`InvalidPlacement`](#invalidplacement) | `invalid placement: <detail>` | A location, kind or runtime that does not exist, or a combination of them (or with the image) that does not. |
| [`NotFound`](#notfound) | `not found: <detail>` | No such sandbox, process, path, forward or session. |
| [`ProviderNotConfigured`](#providernotconfigured) | `provider not configured: <detail>` | The provider is not configured (for example no Fleet credentials). |
| [`Unsupported`](#unsupported) | `unsupported: <detail>` | Not supported by this provider, guest or build. |
| [`SpacesdNotAvailable`](#spacesdnotavailable) | `cua-spacesd is not available: <detail>` | No cua-spacesd answered in the sandbox or at the URL. |
| [`Timeout`](#timeout) | `timed out: <detail>` | A deadline elapsed. |
| [`Fleet`](#fleet) | `fleet: <detail>` | Fleet API failure. |
| [`FleetAdmissionDenied`](#fleetadmissiondenied) | `fleet admission denied: <detail>` | Fleet's admission refused the request: a sandbox or pool size over this account's limits, or a template its policy does not admit. |
| [`CloudCreditExhausted`](#cloudcreditexhausted) | `<detail>` | The account is out of Cua Cloud credit: no credit left, and no card or plan. |
| [`Runtime`](#runtime) | `local runtime: <detail>` | Local runtime failure. |
| [`Env`](#env) | `env: <detail>` | spacesd call failure. |
| [`Http`](#http) | `http: <detail>` | HTTP failure talking to a sandbox service. |
| [`Unauthenticated`](#unauthenticated) | `unauthenticated: <detail>` | Missing or wrong token or ticket. |
| [`PermissionDenied`](#permissiondenied) | `permission denied: <detail>` | The guest OS denied permission. |
| [`Transport`](#transport) | `transport: <detail>` | Could not reach the daemon or the endpoint. |
| [`DaemonNotRunning`](#daemonnotrunning) | `<detail>` | No `cua daemon` is running: nothing listens at its socket or port, or its discovery file (`~/.cua/daemon.json`) was left by a daemon that exited. |
| [`Closed`](#closed) | `closed: <detail>` | The object was closed. |
| [`CapabilityMissing`](#capabilitymissing) | `capability missing: <detail>` | The Space's spacesd reports a feature this call needs as unsupported (the message names it). |
| [`HostCapabilityMissing`](#hostcapabilitymissing) | `host capability missing: <detail>` | A host-side prerequisite (app-session providers, an operator display, a local runtime) is not available. |
| [`TeleportRefused`](#teleportrefused) | `teleport refused: <detail>` | The teleport consent gate refused (or the approver declined). |
| [`PoolSpecMismatch`](#poolspecmismatch) | `pool spec mismatch: <detail>` | A named cloud pool's template differs from the requested sandbox fields; the message holds the diff (pass `apply` to update it). |
| [`ClaimSecretsNotDelivered`](#claimsecretsnotdelivered) | `claim secrets not delivered: <detail>` | A claim bound but its per-claim secrets (the env token) never reached the sandbox within the bounded wait; the claim was released. |
| [`Internal`](#internal) | `internal: <detail>` | Bug or I/O failure. |
| [`AmbiguousSandbox`](#ambiguoussandbox) | `ambiguous sandbox name: <detail>` | A bare sandbox name matches sandboxes in more than one location. |
| [`InsufficientDisk`](#insufficientdisk) | `insufficient disk: <detail>` | A pull, build or VM create would leave less than the configured minimum free disk space (`CUA_DISK_MIN_FREE`, default 5 GiB); nothing was written. |
| [`ImageNotPublished`](#imagenotpublished) | `image not published: <detail>` | A catalog image (an `Image.*` constructor, a tier or `cua sb create <word>`) that CI has not published yet. |
| [`Cancelled`](#cancelled) | `cancelled: <detail>` | The create was cancelled (`Spaces.cancel_create`, Ctrl-C in `cua`, or its caller went away). |
| [`Cloud`](#cloud) | `your cloud: <detail>` | Your own cloud account (AWS, Google Cloud, Modal) refused or failed a call Cua made for a Space there: a missing permission, a quota, a region without the machine type. |

## `InvalidArgument`

**Cause** Bad input.

**Fix** Check the value against the reference; the message names the
argument and what it accepts.

**Message** `invalid argument: <detail>`

**Raised by** [`canonical_image_tier`](</docs/cua-sdk/reference/image#canonical_image_tier>), [`error_doc_url`](</docs/cua-sdk/reference/cua#error_doc_url>), [`fleet_resolve_runtime`](</docs/cua-sdk/reference/fleet/images#fleet_resolve_runtime>), [`qualify_sandbox_ref`](</docs/cua-sdk/reference/sandbox#qualify_sandbox_ref>)

## `InvalidPlacement`

**Cause** A location, kind or runtime that does not exist, or a combination of
them (or with the image) that does not. The message ends with the
valid values for that context.

**Fix** Use one of the values the message lists, or leave `kind` and
`runtime` unset (`auto`). `cua config list` shows the defaults in
effect.

**Message** `invalid placement: <detail>`

**Raised by** [`check_placement`](</docs/cua-sdk/reference/cua#check_placement>)

## `NotFound`

**Cause** No such sandbox, process, path, forward or session.

**Fix** Check the ref, path or id. `Sandboxes.list` (`cua sb ls`) lists the
sandboxes this client can see.

**Message** `not found: <detail>`

**Raised by** [`resolve_image`](</docs/cua-sdk/reference/image#resolve_image>)

## `ProviderNotConfigured`

**Cause** The provider is not configured (for example no Fleet credentials).

**Fix** Set `FLEETS_TOKEN`, or `CUA_CLIENT_ID` and `CUA_CLIENT_SECRET`, or
run `cua auth login` and create the client with `fleet_from_session`.

**Message** `provider not configured: <detail>`

## `Unsupported`

**Cause** Not supported by this provider, guest or build.

**Fix** Use a provider, image or runtime that supports the call; the
message names what is missing.

**Message** `unsupported: <detail>`

**Raised by** [`Sandbox.guest_sh`](</docs/cua-sdk/reference/sandbox/without-spacesd#sandboxguest_sh>), [`fleet_image_variant`](</docs/cua-sdk/reference/fleet/images#fleet_image_variant>), [`fleet_resolve_runtime`](</docs/cua-sdk/reference/fleet/images#fleet_resolve_runtime>), [`resolve_image`](</docs/cua-sdk/reference/image#resolve_image>)

## `SpacesdNotAvailable`

**Cause** No cua-spacesd answered in the sandbox or at the URL.

**Fix** Use an image that runs cua-spacesd (the canonical Linux image does),
or reach the sandbox through the services it declares.

**Message** `cua-spacesd is not available: <detail>`

**Raised by** [`Sandbox.spacesd`](</docs/cua-sdk/reference/sandbox#sandboxspacesd>)

## `Timeout`

**Cause** A deadline elapsed.

**Fix** Raise the timeout (for example `ready_timeout_ms`), and check that
the sandbox or service actually starts.

**Message** `timed out: <detail>`

## `Fleet`

**Cause** Fleet API failure.

**Fix** Read the status in the message. Retry a transient failure; check
the credentials and the account's capacity otherwise.

**Message** `fleet: <detail>`

## `FleetAdmissionDenied`

**Cause** Fleet's admission refused the request: a sandbox or pool size over
this account's limits, or a template its policy does not admit. The
message is Fleet's own and names the limit.

**Fix** Pick a size within the limit the message names (most accounts
run 1-8 vCPUs and 1-32 GiB per sandbox), or contact Cua support to
raise the account's limits.

**Message** `fleet admission denied: <detail>`

**Raised by** [`fleet_size_limits`](</docs/cua-sdk/reference/fleet/images#fleet_size_limits>)

## `CloudCreditExhausted`

**Cause** The account is out of Cua Cloud credit: no credit left, and no card
or plan. New cloud sandboxes and Spaces are refused; running ones
keep running, and local ones are never affected. The message ends
with the website billing page's URL.

**Fix** Add credit on that page (a plan, or a card for pay as you go),
or run the sandbox locally.

**Message** `<detail>`

## `Runtime`

**Cause** Local runtime failure.

**Fix** Run `cua runtime doctor` (`Local.doctor`) and follow the steps it
prints.

**Message** `local runtime: <detail>`

## `Env`

**Cause** spacesd call failure.

**Fix** Read the status in the message; `SpacesdClient.capabilities` tells
whether this spacesd supports the call.

**Message** `env: <detail>`

## `Http`

**Cause** HTTP failure talking to a sandbox service.

**Fix** Check that the service listens on its declared port and answers
HTTP.

**Message** `http: <detail>`

## `Unauthenticated`

**Cause** Missing or wrong token or ticket.

**Fix** Pass the sandbox's env token, refresh the Fleet credentials, or run
`cua auth login` again.

**Message** `unauthenticated: <detail>`

**Raised by** [`Auth.access_token`](</docs/cua-sdk/reference/auth#authaccess_token>), [`resolve_image`](</docs/cua-sdk/reference/image#resolve_image>)

## `PermissionDenied`

**Cause** The guest OS denied permission.

**Fix** Run the call as a guest user allowed to do it, or change the
permissions of the path.

**Message** `permission denied: <detail>`

## `Transport`

**Cause** Could not reach the daemon or the endpoint.

**Fix** Check the address. For a daemon client, start the daemon with `cua
daemon start`.

**Message** `transport: <detail>`

## `DaemonNotRunning`

**Cause** No `cua daemon` is running: nothing listens at its socket or
port, or its discovery file (`~/.cua/daemon.json`) was left by a
daemon that exited. The message says so in plain words.

**Fix** Start Cua (the Spaces app starts the daemon), or run `cua daemon
start`. `Cua.auto` uses the runtime in this process when no daemon
runs.

**Message** `<detail>`

**Raised by** [`Cua.auto`](</docs/cua-sdk/reference/cua#cuaauto>), [`Cua.connect`](</docs/cua-sdk/reference/cua#cuaconnect>)

## `Closed`

**Cause** The object was closed.

**Fix** Open a new handle or session; a closed one stays closed.

**Message** `closed: <detail>`

## `CapabilityMissing`

**Cause** The Space's spacesd reports a feature this call needs as
unsupported (the message names it).

**Fix** Use a Space whose spacesd supports the feature (`Space.supports`),
or update cua-spacesd on it.

**Message** `capability missing: <detail>`

**Raised by** [`Space.screenshot`](</docs/cua-sdk/reference/spaces/space#spacescreenshot>)

## `HostCapabilityMissing`

**Cause** A host-side prerequisite (app-session providers, an operator
display, a local runtime) is not available.

**Fix** Install or start the prerequisite the message names on this
machine.

**Message** `host capability missing: <detail>`

**Raised by** [`Space.stream_session`](</docs/cua-sdk/reference/spaces/streams#spacestream_session>)

## `TeleportRefused`

**Cause** The teleport consent gate refused (or the approver declined).

**Fix** Approve the manifest in the consent callback, or teleport a smaller
scope.

**Message** `teleport refused: <detail>`

**Raised by** [`Space.teleport`](</docs/cua-sdk/reference/spaces/teleport#spaceteleport>)

## `PoolSpecMismatch`

**Cause** A named cloud pool's template differs from the requested sandbox
fields; the message holds the diff (pass `apply` to update it).

**Fix** Pass the pool's own fields, or pass `apply` to update its template.

**Message** `pool spec mismatch: <detail>`

**Raised by** [`Fleet.check_pool_spec`](</docs/cua-sdk/reference/fleet#fleetcheck_pool_spec>)

## `ClaimSecretsNotDelivered`

**Cause** A claim bound but its per-claim secrets (the env token) never
reached the sandbox within the bounded wait; the claim was released.

**Fix** Retry. If it keeps failing, check the pool's claim-secrets setup
and the Fleet status.

**Message** `claim secrets not delivered: <detail>`

**Raised by** [`Fleet.acquire_with`](</docs/cua-sdk/reference/fleet/claims#fleetacquire_with>)

## `Internal`

**Cause** Bug or I/O failure.

**Fix** Report it with the message at https://github.com/trycua/cua/issues.

**Message** `internal: <detail>`

## `AmbiguousSandbox`

**Cause** A bare sandbox name matches sandboxes in more than one location. The
message ends with the qualified candidates (`use one of: local:box,
cloud:box`); `ambiguous_sandbox_candidates` extracts them.

**Fix** Use one of the qualified refs the message lists (`local:<name>`,
`cloud:<name>`).

**Message** `ambiguous sandbox name: <detail>`

**Raised by** [`Sandboxes.connect`](</docs/cua-sdk/reference/sandbox#sandboxesconnect>), [`ambiguous_sandbox_candidates`](</docs/cua-sdk/reference/sandbox#ambiguous_sandbox_candidates>)

## `InsufficientDisk`

**Cause** A pull, build or VM create would leave less than the configured
minimum free disk space (`CUA_DISK_MIN_FREE`, default 5 GiB);
nothing was written.

**Fix** Free space with `cua cache prune`, or lower `CUA_DISK_MIN_FREE`.

**Message** `insufficient disk: <detail>`

## `ImageNotPublished`

**Cause** A catalog image (an `Image.*` constructor, a tier or `cua sb create
&lt;word&gt;`) that CI has not published yet. The message names the
reference.

**Fix** Pass the reference explicitly (`Image.from_registry("<ref>")`,
`cua sb create <ref>`) to use it anyway, or pick a published image
(`cua images ls`).

**Message** `image not published: <detail>`

**Raised by** [`canonical_image_tier`](</docs/cua-sdk/reference/image#canonical_image_tier>), [`omarchy_image`](</docs/cua-sdk/reference/image#omarchy_image>)

## `Cancelled`

**Cause** The create was cancelled (`Spaces.cancel_create`, Ctrl-C in `cua`,
or its caller went away). What it made is gone; the message says
what was removed and what stays (finished image downloads stay
cached, so the next create resumes).

**Fix** Nothing to clean up. Create it again when you want it.

**Message** `cancelled: <detail>`

**Raised by** [`Sandboxes.cancel_create`](</docs/cua-sdk/reference/sandbox#sandboxescancel_create>), [`Spaces.cancel_create`](</docs/cua-sdk/reference/spaces#spacescancel_create>)

## `Cloud`

**Cause** Your own cloud account (AWS, Google Cloud, Modal) refused or failed
a call Cua made for a Space there: a missing permission, a quota, a
region without the machine type. The message names the cloud's own
error.

**Fix** Fix what the message names in that account (`cua cloud test
&lt;provider&gt;` checks it without creating anything), or connect another
region or project.

**Message** `your cloud: <detail>`