Errors

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. cua-spacesd answers RPCs with a google.rpc.Status carrying ErrorInfo; the SDK maps it to the variants below.

Example

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())

Variants#

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, error_doc_url, fleet_resolve_runtime, 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

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

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, fleet_image_variant, fleet_resolve_runtime, 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

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

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, 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, Cua.connect

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

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

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

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

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

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, 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 <word>) 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, 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, Spaces.cancel_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 <provider> checks it without creating anything), or connect another region or project.

Message your cloud: <detail>