Errors

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

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 Spaces.rename, Spaces.set_egress, Spaces.set_volume, canonical_image_tier, error_doc_url, 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 credentials for it).

Fix Set the credentials the message names (for a contrib provider, its environment variable or cua auth provider set <name>).

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, Sandbox.resize, Spaces.set_egress, Spaces.set_network, 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>

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

Raised by Spaces.rename

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

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

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, Hetzner, 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>

HostCapacity#

Cause The machine has no room for another Space now: its VMs are at their memory limit (shared snapshot memory counted once) or CPU limit, or the machine itself is low on memory. Nothing was started. The message says which limit, by how much, and what to do.

Fix Delete a Space, create it smaller (cpus, memory_mb), create it on another machine (on="auto"), or raise the limit on this one (CUA_VM_MAX_RSS_FRACTION, CUA_VM_VCPU_OVERCOMMIT).

Message host capacity: <detail>