> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Exceptions

> Exception hierarchy for cwsandbox error handling.

All cwsandbox exceptions inherit from `CWSandboxError`.

## Hierarchy

```
CWSandboxError
    +-- CWSandboxAuthenticationError
    +-- SandboxError
        +-- SandboxNotRunningError
            +-- SandboxUnavailableError
        +-- SandboxTimeoutError
            +-- SandboxRequestTimeoutError
            +-- SandboxCommandTimeoutError
        +-- SandboxTerminatedError
        +-- SandboxFailedError
        +-- SandboxNotFoundError
        +-- SandboxExecutionError
        +-- SandboxFileError
        +-- SandboxResourceExhaustedError
        +-- SandboxTerminalStateUnavailableError
    +-- DiscoveryError
        +-- RunnerNotFoundError
        +-- ProfileNotFoundError
    +-- FunctionError
        +-- AsyncFunctionError
        +-- FunctionSerializationError
```

## Reference

### CWSandboxError

Source: [src/cwsandbox/exceptions.py:18](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L18)

Base exception for all CWSandbox operations.

**Attributes**

* `reason` (`str | None`): Structured error reason parsed from `google.rpc.ErrorInfo`
  (e.g. `"CWSANDBOX_FILE_NOT_FOUND"`), or `None` when the error
  did not carry AIP-193 details.
* `metadata` (`Mapping[str, str] | None`): Machine-readable metadata from `ErrorInfo.metadata`. Empty
  dict when the error carried no metadata.
* `retry_delay` (`timedelta | None`): Suggested client retry delay parsed from
  `google.rpc.RetryInfo`, or `None` when absent.

### CWSandboxAuthenticationError

Source: [src/cwsandbox/exceptions.py:51](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L51)

Raised when authentication fails.

### SandboxError

Source: [src/cwsandbox/exceptions.py:55](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L55)

Base exception for sandbox operations.

### SandboxNotRunningError

Source: [src/cwsandbox/exceptions.py:59](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L59)

Raised when an operation requires a running sandbox.

### SandboxUnavailableError

Source: [src/cwsandbox/exceptions.py:144](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L144)

Raised when the sandbox service is transiently unavailable.

### SandboxTimeoutError

Source: [src/cwsandbox/exceptions.py:63](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L63)

Raised when a sandbox operation times out.

### SandboxRequestTimeoutError

Source: [src/cwsandbox/exceptions.py:154](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L154)

Raised when a gRPC request exceeded its deadline.

### SandboxCommandTimeoutError

Source: [src/cwsandbox/exceptions.py:162](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L162)

Raised when the user's command inside the sandbox timed out.

### SandboxTerminatedError

Source: [src/cwsandbox/exceptions.py:67](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L67)

Raised when a sandbox was terminated externally.

### SandboxFailedError

Source: [src/cwsandbox/exceptions.py:71](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L71)

Raised when a sandbox fails to start or encounters a fatal error.

### SandboxNotFoundError

Source: [src/cwsandbox/exceptions.py:75](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L75)

Raised when a sandbox is not found (e.g., already deleted).

**Attributes**

* `sandbox_id` (`str | None`): The ID of the sandbox that was not found, or None.

### SandboxExecutionError

Source: [src/cwsandbox/exceptions.py:95](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L95)

Raised when command execution fails inside a sandbox.

**Attributes**

* `exec_result` (`ProcessResult | None`): The `ProcessResult` from the failed execution, or None.
* `exception_type` (`str | None`): Python exception class name from sandbox stderr, or None.
* `exception_message` (`str | None`): Exception message from sandbox stderr, or None.

### SandboxFileError

Source: [src/cwsandbox/exceptions.py:121](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L121)

Raised when a file operation fails in the sandbox.

**Attributes**

* `filepath` (`str | None`): The path of the file that caused the error, or None.

### SandboxResourceExhaustedError

Source: [src/cwsandbox/exceptions.py:171](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L171)

Raised when the sandbox service is under resource pressure.

### SandboxTerminalStateUnavailableError

Source: [src/cwsandbox/exceptions.py:179](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L179)

Raised when the backend does not report a terminal state after stop.

### DiscoveryError

Source: [src/cwsandbox/exceptions.py:195](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L195)

Base exception for discovery operations (runners, profiles).

### RunnerNotFoundError

Source: [src/cwsandbox/exceptions.py:204](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L204)

Raised when a runner ID is not found.

**Attributes**

* `runner_id` (`str`): The ID of the runner that was not found.

### ProfileNotFoundError

Source: [src/cwsandbox/exceptions.py:224](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L224)

Raised when a profile is not found.

**Attributes**

* `profile_name` (`str`): The name of the profile that was not found.
* `runner_id` (`str | None`): The runner ID if specified in the request, or None.

### FunctionError

Source: [src/cwsandbox/exceptions.py:247](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L247)

Base exception for function execution operations.

### AsyncFunctionError

Source: [src/cwsandbox/exceptions.py:251](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L251)

Raised when an async function is passed to @session.function().

### FunctionSerializationError

Source: [src/cwsandbox/exceptions.py:259](https://github.com/coreweave/cwsandbox-client/blob/v0.22.0/src/cwsandbox/exceptions.py#L259)

Raised when arguments, referenced globals, or closures cannot be serialized.