Cortex Sandboxes error reference¶

All errors raised by the Cortex Sandboxes SDK derive from SandboxError, so except SandboxError catches any SDK failure. Handle specific subclasses to respond precisely:

Exception	Meaning	What to do
`SandboxAuthError`	HTTP 401/403 from the Cortex Sandboxes service.	Verify your Snowflake connection is configured and authenticated, and that your role has permission to create sandboxes.
`SandboxBuildError`	Image build failed.	read `exception.logs` for the build output. Common causes are an invalid package name, a network failure during the build, a command that fails in the image definition, or a base image that does not exist.
`SandboxConflictError`	HTTP 409 — the resource already exists or is in a conflicting state.	Use a unique name, connect to the existing sandbox instead of creating a new one, or wait for the conflicting operation to complete.
`SandboxCreateError`	A create reached a terminal `failed` state on the server. NOT retryable.	read `failure`. If `failure.is_probably_transient`, create again; otherwise fix the cause first — the same request will fail the same way.
`SandboxExecError`	Non-zero exit from `Sandbox.exec`. Carries stdout/stderr/exit_code.	Inspect `exception.exit_code`, `exception.stdout`, and `exception.stderr` to diagnose the command failure.
`SandboxExecTimeoutError`	The server enforced its exec deadline, killing the command.	inspect `exception.stdout`/`exception.stderr` to see how far the command got, then raise `timeout=`. For a long-lived process `exec` is the wrong tool – see `Sandbox.create(command=...)`.
`SandboxFileTooLargeError`	A file transfer exceeded the size the platform will carry.	Split the file into smaller chunks or upload via a Snowflake stage and mount it instead.
`SandboxNotFoundError`	HTTP 404 — container or resource missing.	The sandbox id is invalid or the sandbox was already terminated. Re-create it.
`SandboxNotImplementedError`	A surfaced SDK method has no backend and will not until one lands.	Remove the unsupported parameter or feature flag from your code. This is not a transient failure — retrying will not help.
`SandboxNotReadyError`	Container not ready: HTTP 409 cold-start exhausted, or async create timed out.	Wait a moment and retry, or increase the `timeout=` passed to `wait_until_ready()`.
`SandboxRateLimitError`	HTTP 429 after the SDK retry budget.	Two different conditions raise this, and they need opposite responses. If `exception.retry_after` is set, the server named a wait time – honour it, or reduce request concurrency. If it is `None`, suspect the per-identity live-sandbox cap (100 by default): that 429 does not clear with time, only when you terminate something, so retrying cannot succeed. The cap is a guardrail against a runaway create loop, not a precise limit. Under concurrent creates, the number of live sandboxes can briefly exceed 100. List what you hold with `Sandbox.list()` and call `terminate()` on what you no longer need. A suspended sandbox still counts – only terminated and failed ones stop consuming quota.
`SandboxTransportError`	5xx, DNS, connection, or read-timeout failures after retries.	Check network connectivity and Snowflake service status, then retry.
`SandboxValidationError`	HTTP 400 — the request parameters are invalid.	Check the error message for which parameter is invalid. The message usually includes the specific field and why it was rejected.
`ShellClosed`	Raised when input is sent to a shell whose process has exited.	The shell is gone and will not come back – reopen one with `Sandbox.shell()` rather than retrying the send. Check `SyncShell.closed` (or catch this) before writing if the remote command may have exited on its own.

SandboxContractWarning is a UserWarning, not an exception. It is emitted when the server returns something the SDK does not recognize. Filter with warnings.filterwarnings if needed.

Two error categories fall outside the SandboxError hierarchy: configuration problems raise RuntimeError (for example, an unconfigured client or unresolvable connection), and some transport conditions surface as asyncio.TimeoutError. Guard those separately.

For general diagnostic guidance (connection setup, container recovery, CLI authentication), see Troubleshooting Cortex Sandboxes.