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