microvm_runtime/
error.rs

1use thiserror::Error;
2
3/// Convenience alias used throughout runtime providers.
4pub type VmRuntimeResult<T> = Result<T, VmRuntimeError>;
5
6/// Errors that can occur during microVM lifecycle or query operations.
7#[derive(Debug, Error)]
8pub enum VmRuntimeError {
9    /// Attempted to create a VM with an identifier that is already in use.
10    #[error("vm '{0}' already exists")]
11    VmAlreadyExists(String),
12
13    /// Referenced a VM identifier that does not exist.
14    #[error("vm '{0}' not found")]
15    VmNotFound(String),
16
17    /// A lifecycle transition was requested that is not valid from the current state.
18    #[error("invalid vm transition for '{vm_id}': {from} -> {to}")]
19    InvalidTransition {
20        vm_id: String,
21        from: String,
22        to: &'static str,
23    },
24
25    /// Attempted to create a snapshot with an identifier that already exists on the VM.
26    #[error("snapshot '{snapshot_id}' already exists for vm '{vm_id}'")]
27    SnapshotAlreadyExists { vm_id: String, snapshot_id: String },
28
29    /// Attempted to restore from a snapshot that does not exist on disk.
30    #[error("snapshot '{snapshot_id}' not found for vm '{vm_id}'")]
31    SnapshotNotFound { vm_id: String, snapshot_id: String },
32
33    /// Internal lock was poisoned by a panicking thread.
34    #[error("provider state lock poisoned")]
35    StatePoisoned,
36
37    /// Backend is not supported in the current build/config.
38    #[error("backend unsupported: {0}")]
39    Unsupported(String),
40
41    /// Metrics poller failed to open, parse, or read the FC metrics FIFO.
42    #[error("metrics: {0}")]
43    Metrics(String),
44
45    /// Graceful shutdown of a child process failed (signal delivery, wait, or
46    /// escalation step).
47    #[error("shutdown failed: {0}")]
48    Shutdown(String),
49
50    /// Host egress firewall (iptables) setup or teardown failed, or input
51    /// validation rejected a rule before any iptables call was made.
52    #[error("firewall error: {0}")]
53    Firewall(String),
54
55    /// Jailer chroot preparation, command construction, or teardown failed.
56    #[error("jailer error: {0}")]
57    Jailer(String),
58
59    /// Network configuration is malformed (bad CIDR, prefix out of range, etc).
60    #[error("network config invalid: {0}")]
61    NetworkConfig(String),
62
63    /// Host network setup or teardown failed (bridge/NAT/forward/TAP).
64    #[error("network setup failed: {0}")]
65    NetworkSetup(String),
66
67    /// Rootfs catalog discovery, per-VM clone, or SHA-256 integrity check
68    /// failed (missing template, stamp mismatch, hash mismatch, I/O error).
69    #[error("rootfs: {0}")]
70    Rootfs(String),
71
72    /// Userfaultfd page-fault handler failed to bind, hand-shake, or service
73    /// page faults. The variant is intentionally a free-form message because
74    /// the failure modes range from libc errno values to JSON parse errors on
75    /// the region-mapping payload Firecracker sends with the fd.
76    #[error("uffd error: {0}")]
77    Uffd(String),
78}
microvm_runtime/error.rs

microvm_runtime/
error.rs
