Enum RightsizeError 

pub enum RightsizeError {
    UnsupportedByBackend {
        feature: String,
        backend: String,
        remedy: Option<String>,
    },
    PortBindConflict {
        message: String,
        source: Option<Box<RightsizeError>>,
    },
    ContainerLaunch(String),
    Backend(String),
    NameConflict {
        message: String,
        source: Option<Box<RightsizeError>>,
    },
    ReuseNetworkConflict {
        network_id: String,
    },
    ReuseCheckpointConflict,
    IsolationRequired {
        backend: String,
    },
    CheckpointUnsupported {
        backend: String,
    },
    CheckpointBackendMismatch {
        active_backend: String,
        checkpoint_backend: String,
    },
    InvalidCheckpointName {
        name: String,
    },
    CheckpointArtifactMissing {
        checkpoint_ref: String,
        backend: String,
    },
    MalformedArchive {
        path: PathBuf,
        reason: String,
    },
    Provision(String),
    Io(Error),
}

The error type returned by every fallible rightsize operation.

Variants

UnsupportedByBackend

A backend was asked for a capability it does not implement — e.g. microsandbox asked to install a network link into an image with no nc. remedy, when given, is appended after an em-dash as a hint (try a different backend, fix the image, etc.).

Fields

feature: String

A short noun phrase naming what’s unsupported (never the advice itself).

backend: String

The backend’s registered name (e.g. "microsandbox", "docker").

remedy: Option<String>

Optional actionable advice, rendered after an em-dash.

PortBindConflict

A backend’s start() failed because a host port it tried to bind was already in use by something else. The container port-retry loop classifies this case — typed first, string-matched fallback — and retries with fresh ports.

Fields

message: String

The rendered failure message (backend-specific wording is fine here).

source: Option<Box<RightsizeError>>

The underlying error, when a backend can supply one (e.g. the daemon’s own error chain), so source() still walks to it.

ContainerLaunch(String)

A container’s wait strategy never became ready before its startup timeout. The message carries the wait target’s describe() plus its last 50 log lines, so a failure is diagnosable from the test output alone.

Backend(String)

A subprocess or daemon call failed outright (non-zero exit, non-2xx response). The message carries the full stderr or response body — never a truncated summary — so the failure is diagnosable from the test output alone.

NameConflict

A backend’s create() failed because another process already created a sandbox with this name — the reuse start flow’s cue (see crate::reuse::is_name_conflict) to re-enter the adopt path once, on the theory that the winner is about to (or already did) register itself in the reuse registry. Typed first, string-matched (“already exists”) fallback, mirroring RightsizeError::PortBindConflict’s own classification shape.

Fields

message: String

The rendered failure message (backend-specific wording is fine here).

source: Option<Box<RightsizeError>>

The underlying error, when a backend can supply one, so source() still walks to it.

ReuseNetworkConflict

.reuse(true) was combined with .with_network(...). Reuse’s identity hash covers only image/env/command/ports/mounts — never cross-container network topology — so this combination has no well-defined adopt/create behavior.

Fields

network_id: String

The network id the container was trying to join.

ReuseCheckpointConflict

.reuse(true) was combined with Container::from_checkpoint(...). Reuse’s identity hash has no concept of a checkpoint reference (checkpoint_ref deliberately does not enter it), so this combination has no well-defined adopt/create behavior. Raised in Container::start(), before any backend work, once reuse is fully active (both opt-ins) — mirrors RightsizeError::ReuseNetworkConflict’s own gating.

IsolationRequired

.require_isolation(true) was set on a Container but the active backend’s capabilities().hardware_isolated is false — e.g. the docker backend, which shares the host kernel. Raised in Container::start(), before any create/network work: no sandbox is created. The message names the active backend and the remedy (switch to the msb backend).

Fields

backend: String

The active backend’s registered name (e.g. "docker").

CheckpointUnsupported

ContainerGuard::checkpoint() was called but the active backend’s capabilities().checkpoint is false — every real backend has it today (docker via image commit, microsandbox via disk snapshots); this only fires for a test double that hasn’t opted in. Raised BEFORE any backend call (see ContainerGuard::checkpoint’s doc). The message names the backend and points at the checkpoints docs, without steering toward a specific other backend.

Fields

backend: String

The active backend’s registered name (a test double’s, in practice — see the variant doc).

CheckpointBackendMismatch

Container::from_checkpoint(&cp) was started under a different active backend than the one that created cp (Checkpoint::backend) — a docker-committed image cannot boot as a microsandbox snapshot ref, and vice versa. Raised in Container::start(), before any backend work. The same variant is also raised by Checkpoint::export_to/Checkpoint::import_from when the active backend doesn’t match the checkpoint’s/archive’s creator, before any backend or filesystem work in either case. The message names both backends and the RIGHTSIZE_BACKEND=<creator> remedy.

Fields

active_backend: String

The currently active backend’s registered name.

checkpoint_backend: String

The backend that created the checkpoint being restored.

InvalidCheckpointName

A named checkpoint’s name failed the checkpoints feature’s validation regex (^[a-z0-9][a-z0-9-]{0,40}$) — raised by ContainerGuard::checkpoint_named, Checkpoint::find, and Checkpoint::remove, before any backend call or registry I/O in every case. The regex is the same across every port of this library (a cross-language contract), so a name rejected here is rejected everywhere.

Fields

name: String

The rejected name, verbatim.

CheckpointArtifactMissing

Checkpoint::export_to(...) was called on a checkpoint whose backend-native artifact is no longer there (SandboxBackend::has_checkpoint returned false) — exporting it would either fail partway through or produce an archive whose artifact member is missing/empty, so this is raised before any staging or archive work begins.

Fields

checkpoint_ref: String

The checkpoint ref that no longer has a backend-native artifact.

backend: String

The backend it was supposedly created on.

MalformedArchive

Checkpoint::import_from(...) was given a path that isn’t a valid rightsize checkpoint archive — the file doesn’t exist or isn’t a tar, it’s missing the checkpoint.json member, that member doesn’t parse as JSON, or its rightsizeArchive field isn’t a version this port understands. Raised before any backend call or registry write in every case.

Fields

path: PathBuf

The archive path that was rejected.

reason: String

A short phrase naming exactly what’s wrong with it.

Provision(String)

The msb toolchain provisioner failed (download, checksum, install).

Io(Error)

A host I/O operation failed (binding a port, reading a socket, writing a temp file). Wrapped rather than matched on, since the original io::Error already carries a precise Display.

Implementations

impl RightsizeError

pub fn unsupported( feature: impl Into<String>, backend: impl Into<String>, ) -> Self

Builds a RightsizeError::UnsupportedByBackend without a remedy.

pub fn unsupported_with_remedy( feature: impl Into<String>, backend: impl Into<String>, remedy: impl Into<String>, ) -> Self

Builds a RightsizeError::UnsupportedByBackend with a remedy appended after an em-dash.

Trait Implementations

impl Debug for RightsizeError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for RightsizeError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for RightsizeError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for RightsizeError

fn from(source: Error) -> Self

Converts to this type from the input type.