Enum SnapshotError 

#[non_exhaustive]
pub enum SnapshotError {
    QuiesceTimeout,
    MagicMismatch {
        found: u64,
        expected: u64,
    },
    VersionMismatch {
        found: Version,
        expected: Version,
    },
    CrcMismatch,
    TooShort,
    Incompatible,
    AtomicCommitFailed(Error),
    AtomicCommitCrossFs {
        dest: PathBuf,
        temp_dir: PathBuf,
    },
    InvalidPath(String),
    Bitcode(String),
    SizeLimitExceeded {
        limit: usize,
    },
    MemoryIo(Error),
    Io(Error),
    Capture(String),
}

Errors produced by the snapshot subsystem.

Variants and their Display shapes are wire-stable per I-RC-8: the API layer surfaces to_string() verbatim into the fault_message body. Renaming a variant or its message is a compat-suite golden change.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

QuiesceTimeout

A vCPU did not acknowledge the quiesce request within the timeout.

Surfaces as 503 Service Unavailable on PUT /snapshot/create. The save is aborted; the previous on-disk pair (if any) is untouched.

MagicMismatch

Snapshot magic mismatch — the file is not a squib-/Firecracker-compatible state file.

Fields

found: u64

Magic value read from the file header.

expected: u64

Magic value squib expected (architecture-specific).

VersionMismatch

Snapshot version is not loadable by this squib build.

The compat rule mirrors upstream: major must match exactly; minor must be ≤ ours; patch is unrestricted.

Fields

found: Version

Version embedded in the file.

expected: Version

Version this squib build emits.

CrcMismatch

CRC64 of the file body does not match its trailing checksum.

TooShort

The file is shorter than the trailing 8-byte CRC.

Incompatible

Snapshot deserializes to a structurally compatible state, but the contents (sysreg subset, GIC blob shape) are from a different VMM.

AtomicCommitFailed(Error)

Atomic-commit failed: the temp file wrote successfully but rename(2) did not complete. The previous destination pair (if any) is left untouched.

AtomicCommitCrossFs

The user-supplied destination path and the temp-file directory live on different filesystems, so rename(2) could not be atomic.

Pre-flight check; surfaces before any data is written. The remediation is for the operator to point the snapshot at a path on the same filesystem as the temp directory (or vice-versa).

Fields

dest: PathBuf

User-supplied destination path.

temp_dir: PathBuf

Directory in which the temp file would have been created.

InvalidPath(String)

Operator handed the API a path that did not pass boundary validation (NUL byte, oversized, traversal).

Bitcode(String)

bitcode failed to encode or decode the snapshot envelope.

Display matches Self::wire_message so the API server’s fault_message body is byte-equal to the rendered to_string().

SizeLimitExceeded

The file is larger than the squib deserialization size limit.

Fields

limit: usize

The configured limit.

MemoryIo(Error)

Memory file write failed (sparse pwrite, full dump, or fsync).

Io(Error)

Generic I/O error during state file read/write or fsync.

Capture(String)

A host-side capture or restore step failed (HVF call returned an error, MMDS handle was poisoned, etc.). The string is the underlying cause for the fault_message; the variant exists to keep host-FFI failures out of Bitcode and Io (both of which connote different remediations).

Implementations

impl SnapshotError

pub fn wire_message(&self) -> String

The exact fault_message body string this error surfaces to the API.

Stable per I-RC-8 — renaming a variant or its Display shape is a compat-suite golden change. Single-source-of-truth: this delegates to Display, so the two cannot drift.

Trait Implementations

impl Debug for SnapshotError

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

Formats the value using the given formatter.

impl Display for SnapshotError

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

Formats the value using the given formatter.

impl Error for SnapshotError

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 SnapshotError

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for SnapshotError

fn from(err: Error) -> Self

Converts to this type from the input type.