# What Errors Can Occur When Using microsandbox? Complete `MicrosandboxError` Reference > Explore MicrosandboxError variants including I/O failures, HTTP timeouts, and sandbox conflicts. Understand common errors and their resolutions for robust application development. - Repository: [Super Rad Company/microsandbox](https://github.com/superradcompany/microsandbox) - Tags: api-reference - Published: 2026-08-20 --- **microsandbox reports a rich set of typed error variants—from I/O failures and HTTP timeouts to sandbox lifecycle conflicts and snapshot corruption—all centralized in a single `MicrosandboxError` enum.** The microsandbox Rust SDK defines every possible failure mode in one central error module. When you build against `superradcompany/microsandbox`, understanding what errors can occur when using microsandbox lets you handle `MicrosandboxResult` returns precisely instead of relying on fragile string parsing. ## I/O, System, and Network Errors Low-level problems with the host operating system or remote connections surface through several distinct variants. ### `Io`, `Nix`, and `WindowsHostSetup` Files, sockets, or OS-specific prerequisites trigger these variants. In [`sdk/rust/lib/error.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/error.rs), `MicrosandboxError::Io` wraps standard `std::io::Error` cases (lines 13–16), while `Nix` (lines 99–101) captures Linux-specific failures and `WindowsHostSetup` (lines 103–106) covers Windows host prerequisites. ### `Http` and `CloudHttp` Remote requests to external services or the cloud control plane return `Http` (lines 17–20) or `CloudHttp` (lines 21–30). These variants wrap the underlying HTTP client errors so you can distinguish between generic network failures and cloud-specific rejections. ### `NetworkBuilder` Invalid network-policy specifications, including DNS config, produce `NetworkBuilder` (lines 48–55). This catches malformed firewall or interface rules before they reach the runtime. ## Database, Configuration, and Serialization Errors Data-layer and config problems are surfaced explicitly so callers can fix inputs without debugging opaque stack traces. ### `Database` Underlying `sea_orm` interaction failures—such as schema mismatches or connection loss—raise `Database` (lines 36–38). ### `InvalidConfig` When the SDK receives malformed or contradictory configuration data, it returns `InvalidConfig` (lines 40–42). This prevents silent misconfigurations from reaching the runtime. ### `Json` `MicrosandboxError::Json` (lines 86–88) signals that `serde_json` failed to serialize or deserialize data flowing between the host and guest. This typically appears when agent messages or snapshot metadata are corrupt. ## Sandbox Lifecycle Errors Creating, starting, stopping, or inspecting a sandbox can fail in predictable ways that you can match against. ### `SandboxNotFound`, `SandboxAlreadyExists`, and Related State Errors As implemented in [`sdk/rust/lib/error.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/error.rs), the SDK guards sandbox state with: - `SandboxNotFound` (lines 50–52) - `SandboxAlreadyExists` (lines 54–60) - `SandboxStillRunning` (lines 62–64) - `SandboxNotRunning` (lines 66–68) These let you detect race conditions or stale handles without parsing error strings. ### `NoDefaultCommand` If a sandbox configuration omits a default command and the caller provides none, the SDK returns `NoDefaultCommand` (lines 44–48). ## Runtime and Boot Errors ### `Runtime` and `BootStart` Guest VM crashes or unreachable agent relays raise `Runtime` (lines 70–72) or `BootStart` (lines 74–84). The `BootStart` variant is especially detailed: it includes the parsed [`boot-error.json`](https://github.com/superradcompany/microsandbox/blob/main/boot-error.json) record so you can inspect why the guest failed to initialize. ## Execution and Communication Errors ### `ExecTimeout` and `ExecFailed` Commands inside the sandbox either exceed the timeout (`ExecTimeout`, lines 108–110) or fail to spawn (`ExecFailed`, lines 115–119). You can catch these to implement retry logic or fallback commands. ### `Protocol` and `AgentClient` When the low-level `microsandbox_protocol` or the higher-level client cannot talk to the agent, the SDK emits `Protocol` (lines 90–92) or `AgentClient` (lines 94–96). These usually indicate version mismatches or broken UNIX socket connections. ## Filesystem, Volume, and Image Errors ### `SandboxFsOps` and `Terminal` Operations on the sandbox’s virtual filesystem raise `Terminal` (lines 121–123) or `SandboxFsOps` (lines 124–127). These cover terminal allocation failures and broader filesystem operation errors. ### `VolumeNotFound`, `VolumeAlreadyExists`, and `ImageNotFound` Volume and image layers in [`sdk/rust/lib/volume/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/volume/mod.rs) and related modules can emit `VolumeNotFound` (lines 36–38), `VolumeAlreadyExists`, and `ImageNotFound` (lines 28–30). These errors map directly to the state of the local image store and volume registry. ## Snapshot, Patch, and Migration Errors ### `SnapshotIntegrity`, `SnapshotMigration`, and `PatchFailed` The snapshot subsystem in [`sdk/rust/lib/snapshot/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/snapshot/mod.rs) uses typed errors for every failure mode: - `SnapshotIntegrity` (lines 76–78) reports corrupted snapshot data. - `SnapshotMigration` (lines 80–91) covers failed schema or format migrations. - `PatchFailed` (lines 56–58) signals that a root-fs patch could not be applied. ## Observability and Backend Errors ### `MetricsDisabled` and `MetricsUnavailable` When metrics sampling is turned off or no samples have been produced yet, the SDK returns `MetricsDisabled` (lines 93–95) or `MetricsUnavailable` (lines 96–99). ### `MissedRotation` and `InvalidCursor` Log-stream readers that lose data due to file rotation receive `MissedRotation` (lines 101–108). An unreadable cursor produces `InvalidCursor` (lines 113–117). ### `Unsupported` and `Custom` If the current backend cannot perform the requested operation, the SDK returns `Unsupported` (lines 119–127). This variant carries an `Operation` enum value and an `UnsupportedReason`, letting you branch programmatically without string parsing. For edge cases, `Custom` (lines 129–131) accepts caller-defined error messages. ## The `MicrosandboxResult` Alias and `Operation` Enum Every public SDK function returns `MicrosandboxResult`, defined as: ```rust pub type MicrosandboxResult = Result; ``` The `Operation` enum (lines 37–74 in [`sdk/rust/lib/error.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/error.rs)) lists every public API call—such as `SandboxCreate`, `VolumeCreate`, and `SnapshotOps`. When paired with `Unsupported { op, reason }`, it gives you structured context about which API was blocked and why. ## Handling microsandbox Errors in Code ### Matching on Sandbox Lifecycle Errors ```rust use microsandbox::sdk::rust::{Sandbox, MicrosandboxError}; fn create_and_start(name: &str) -> Result<(), MicrosandboxError> { let sb = Sandbox::create(name)?; sb.start()?; Ok(()) } fn main() { match create_and_start("demo") { Ok(()) => println!("sandbox running"), Err(e) => match e { MicrosandboxError::SandboxAlreadyExists(_) => { eprintln!("Sandbox already exists – drop the old handle or use `replace_existing`"); } MicrosandboxError::InvalidConfig(msg) => { eprintln!("Invalid configuration: {msg}"); } MicrosandboxError::Unsupported { op, reason } => { eprintln!("Operation `{}` unsupported: {}", op.api_path(), reason.hint()); } other => { eprintln!("Unexpected error: {other}"); } }, } } ``` Key variants used above are defined at `SandboxAlreadyExists` (lines 54–60), `InvalidConfig` (lines 40–42), and `Unsupported` (lines 119–127). ### Detecting Snapshot Corruption ```rust use microsandbox::sdk::rust::{Snapshot, MicrosandboxError}; fn verify_snapshot(path: &str) -> Result<(), MicrosandboxError> { let snap = Snapshot::load(path)?; snap.verify()?; Ok(()) } match verify_snapshot("snap.img") { Ok(_) => println!("snapshot is valid"), Err(MicrosandboxError::SnapshotIntegrity(details)) => { eprintln!("Snapshot corrupted: {details}"); } Err(err) => eprintln!("Other error: {err}"), } ``` The `SnapshotIntegrity` variant is defined at lines 76–78. ### Propagating Custom Errors ```rust use microsandbox::sdk::rust::MicrosandboxError; fn my_wrapper() -> Result<(), MicrosandboxError> { if something_wrong { return Err(MicrosandboxError::Custom( "my wrapper detected an invariant breach".into(), )); } Ok(()) } ``` The `Custom` variant is defined at lines 129–131. ## Key Source Files for Error Handling - **[`sdk/rust/lib/error.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/error.rs)** — Central `MicrosandboxError` enum, `MicrosandboxResult` alias, `Operation` enum, and `UnsupportedReason`. - **[`sdk/rust/lib/volume/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/volume/mod.rs)** — Volume-related API that emits `VolumeNotFound`, `VolumeAlreadyExists`, and `Unsupported`. - **[`sdk/rust/lib/snapshot/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/snapshot/mod.rs)** — Snapshot creation, verification, and migration logic that emits `Snapshot*` errors. - **[`sdk/rust/lib/setup/windows.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/setup/windows.rs)** — Windows host prerequisite errors (`WindowsHostSetup`). - **[`sdk/rust/lib/setup/linux.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/setup/linux.rs)** — Linux-specific host setup errors (`Nix`). - **[`sdk/rust/lib/agent.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/agent.rs)** — Agent client errors (`AgentClient`). - **[`crates/utils/lib/secret.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/utils/lib/secret.rs)** — Helper for secret-related failures consumed by `InvalidConfig`. ## Summary - microsandbox centralizes all failures in the `MicrosandboxError` enum inside [`sdk/rust/lib/error.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/error.rs). - Errors span every layer: **I/O**, **network**, **database**, **configuration**, **sandbox lifecycle**, **runtime**, **serialization**, **protocol**, **execution**, **filesystem**, **snapshots**, **metrics**, **logging**, and **backend support**. - All public functions return `MicrosandboxResult`, making error composition explicit. - The `Unsupported` variant pairs with the `Operation` enum to provide structured, parse-free error handling. - Snapshot, volume, and sandbox subsystems each contribute domain-specific variants such as `SnapshotIntegrity`, `VolumeNotFound`, and `SandboxAlreadyExists`. ## Frequently Asked Questions ### What is the root error type in microsandbox? The root error type is `MicrosandboxError`, an exhaustive enum defined in [`sdk/rust/lib/error.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/error.rs). It acts as the single source of truth for error handling across the CLI, language bindings, and runtime. ### How do I distinguish between a sandbox that does not exist and one that is already running? Match on `MicrosandboxError::SandboxNotFound` (lines 50–52) when the requested sandbox is missing. Use `MicrosandboxError::SandboxStillRunning` (lines 62–64) or `SandboxNotRunning` (lines 66–68) when the sandbox is in the wrong state for the operation. ### Can I programmatically detect if a backend does not support an operation? Yes. Check for `MicrosandboxError::Unsupported { op, reason }` (lines 119–127). The `op` field is an `Operation` enum that identifies the exact API call, and `reason` explains why the backend declined it. ### What should I do when a snapshot fails verification? Catch `MicrosandboxError::SnapshotIntegrity` (lines 76–78). This variant includes detailed failure information, allowing you to log the corruption and recreate the snapshot from a known good source.