Skip to main content
Every SDK failure carries the same taxonomy: catch the base SailError for everything, or match a specific failure.

Command failure is not an exception

A command that runs to completion and exits nonzero is not an SDK failure. run and exec(...).wait() return normally with the exit code on the result; check it yourself:
To treat command failure as an error, pass check to run: a nonzero exit or a timeout then raises CommandFailedError, which carries the completed result. Rust has no check; it reports a nonzero exit through the returned ExecResult, so use the exit-code check above.
Exec errors in the taxonomy below cover the SDK failing to run the command at all, not the command’s own exit status.

The taxonomy

Every class derives from sail.SailError. The Python classes that match a Python builtin also inherit it (NotFoundError is a LookupError, TimeoutError the builtin TimeoutError, ApiError a RuntimeError, and so on), so handlers written against the builtins keep working. API and creation failures carry status_code (status in TypeScript) and the parsed response body. Every error carries a retryable flag: True means retrying the same call may succeed (the failure was transient, like a network drop or a busy service), False means it is deterministic and a retry would just fail the same way.

Notable errors

Creation failed

Raised when Sailbox.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: calling exec 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: 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.