Exceptions

Overview

Every exception the SDK raises is either a remote user exception — your own function code raised something on the remote side — or a platform error — the SDK, the control plane, or the fleet failed to run your code at all. The two are never conflated: RemoteFunctionError (an alias of RemoteError) is the sole carrier for the former; everything else descends from FabricError.

class FabricError(Exception):
    """Base class for every platform-side error surfaced by the SDK."""

APIError family

Raised when the control plane returns its standard JSON error envelope. code is the stable, machine-readable identifier (SCREAMING_SNAKE_CASE); unknown codes are tolerated and simply surface as the base APIError.

class APIError(FabricError):
    def __init__(
        self,
        code: str,
        message: str,
        *,
        status_code: Optional[int] = None,
        details: Optional[Mapping[str, Any]] = None,
    ) -> None: ...

code str

Stable machine error code, e.g. NOT_FOUND or GPU_QUOTA_EXCEEDED.

message str

Human-readable message from the API envelope (available as **.api_message**).

status_code Optional[int]Default: None

HTTP status code of the response, when known.

details Optional[Mapping[str, Any]]Default: None

Structured error payload (available as **.details**, defaults to {}).

RunError family

Raised when a run or call fails for an infrastructure reason — never for a user exception. code mirrors the run's own error code from the wire protocol; the SDK maps known codes to a more specific subclass with an actionable message, and falls back to the base RunError for anything unrecognized.

class RunError(FabricError):
    code: str = "INTERNAL"

    def __init__(
        self,
        message: str,
        *,
        code: Optional[str] = None,
        run_id: Optional[str] = None,
        details: Optional[Mapping[str, Any]] = None,
    ) -> None: ...

message str

Actionable, human-readable error message.

code Optional[str]Default: None

Overrides the subclass's default **.code** when given.

run_id Optional[str]Default: None

The run/call id this error belongs to, when known.

details Optional[Mapping[str, Any]]Default: None

Structured details, e.g. last_error_code for RetriesExhaustedError.

RemoteError / RemoteFunctionError

RemoteFunctionError (an alias of RemoteError) wraps an exception raised by your own function on the remote side. When the original exception type can be unpickled locally, the SDK re-raises it directly with the remote traceback attached — so except ValueError on your own code still works across the network. RemoteError/RemoteFunctionError is only used as a fallback wrapper when the original exception can't be reconstructed locally (e.g. it's defined in a module the client doesn't have).

class RemoteError(FabricError):
    def __init__(
        self,
        exc_type: str,
        message: str,
        remote_traceback: str,
    ) -> None: ...

# Alias kept for parity with the runner-protocol wording.
RemoteFunctionError = RemoteError

exc_type str

Qualified name of the original remote exception type (available as **.exc_type**).

message str

The original exception's message (available as **.remote_message**).

remote_traceback str

The full remote traceback text (available as **.remote_traceback**), appended to str(exc) for readability.

Connection & cancellation

class RunCancelled(FabricError):
    def __init__(self, run_id: str, *, message: Optional[str] = None) -> None: ...

Sandbox errors

Sandbox methods (exec, put_file, get_file, ls, tunnel) raise a family of APIError subclasses for well-known conflict/limit conditions, plus two FabricError-derived exceptions for lifecycle failures.

class SandboxTerminatedError(FabricError):
    def __init__(self, sandbox_id: str, code: str, message: str) -> None: ...

class SandboxFailedError(FabricError):
    def __init__(self, sandbox_id: str, code: str, message: str) -> None: ...

Image build & volume errors

class ImageBuildError(FabricError):
    def __init__(
        self,
        build_id: str,
        code: str,
        message: str,
        *,
        definition_hash: Optional[str] = None,
    ) -> None: ...

build_id str

Id of the failed build (available as **.build_id**); pass it to blade image logs <build_id>.

code str

The build's own error code: IMAGE_BUILD_FAILED, IMAGE_BUILD_TIMEOUT, IMAGE_PUSH_FAILED, or INTERNAL.

message str

Build failure message (available as **.build_message**).

definition_hash Optional[str]Default: None

Content hash of the image definition, when available.

Raised when a bladekit.Image build does not reach succeeded. The message always points you at the CLI command to inspect the build logs.

class VolumeCommitError(FabricError):
    def __init__(self, code: str, message: str) -> None: ...

Catch patterns

Catch RemoteFunctionError (or your own exception types, which are re-raised as-is when unpicklable) to handle failures in your code, RunError subclasses for retryable infrastructure failures, and the narrower APIError subclasses for request-time problems.

import bladekit

try:
    result = my_function.remote(x)
except bladekit.RemoteFunctionError as exc:
    # Your own function raised something the client couldn't reconstruct.
    print(f"user code failed remotely: {exc}")
except bladekit.NodeLostError:
    # Transient infra failure — safe to retry.
    result = my_function.remote(x)
except bladekit.RetriesExhaustedError as exc:
    print("gave up after retries; last error:", exc.details.get("last_error_code"))
except bladekit.RunError as exc:
    # Any other infra failure: CONTAINER_FAILED, IMAGE_PULL_FAILED, TIMEOUT, ...
    raise
except bladekit.NotFoundError:
    print("the app or function no longer exists")

Related reference