SailError
for everything, or match a specific failure.
The taxonomy
| Failure | Python | TypeScript | Rust SailError:: |
|---|---|---|---|
| Creation failed | SailboxCreationError | SailboxCreationError | Creation |
| Custom image build failed | ImageBuildError | ImageBuildError | ImageBuild |
| Exec failed | SailboxExecutionError | SailboxExecutionError | Execution |
| Sailbox gone (terminated) | SailboxTerminatedError | SailboxTerminatedError | Terminated |
| Unknown exec request | SailboxExecRequestNotFoundError | SailboxExecRequestNotFoundError | ExecRequestNotFound |
| Host machine lost mid-run | SailboxWorkerLostError | SailboxWorkerLostError | WorkerLost |
| Unknown id / unexposed port | LookupError | NotFoundError | NotFound |
| Auth failure | PermissionError | PermissionDeniedError | PermissionDenied |
| Invalid argument | ValueError | InvalidArgumentError | InvalidArgument |
| Missing guest file | FileNotFoundError | FileNotFoundError | FileNotFound |
| Readiness or build timeout | TimeoutError | TimeoutError | Transport (timeout) |
| Writing to a closed stdin | BrokenPipeError | BrokenPipeError | BrokenPipe |
| Network/transport failure | ConnectionError | TransportError | Transport |
| Unexpected API response | RuntimeError | ApiError | Api |
LookupError, PermissionError, ValueError,
FileNotFoundError, TimeoutError, BrokenPipeError, ConnectionError)
where they are the natural fit; the SDK-specific classes all derive from sail.SailboxError,
itself under sail.SailError.
Notable errors
Creation failed
Raised whenSailbox.create fails. When
creation succeeded but SSH setup failed (with ssh=True), the message carries
the new sailbox’s id so you can fetch it to retry enable_ssh or terminate
it.
Host machine lost mid-run
The machine hosting your sailbox failed before the command finished. The command may have run only partially, and its output is gone. The run cannot be resumed: callingexec again starts it over from the
beginning, so any side effects the partial run applied will happen again. The
sailbox itself recovers automatically; you do not need to resume it.
Function errors (Python only)
SailboxFunctionError is raised when a
@sail.function call fails while running
in the sailbox. It carries the remote failure context:
| Attribute | Type | Description |
|---|---|---|
error_type | str | Remote exception class name. |
traceback | str | Remote traceback text. |
stdout | str | Captured remote stdout. |
stderr | str | Captured remote stderr. |
SailboxFunctionSerializationError is raised when a function payload or
result cannot be serialized, or the remote function runtime cannot be prepared
(including a Python major.minor version mismatch between your local
interpreter and the sailbox’s python3). Both are subclasses of
SailboxExecutionError.