What Errors Can Occur When Using microsandbox? Complete `MicrosandboxError` Reference

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<T> 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, 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, 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 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 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 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<T>, defined as:

pub type MicrosandboxResult<T> = Result<T, MicrosandboxError>;

The Operation enum (lines 37–74 in 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

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

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

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 — Central MicrosandboxError enum, MicrosandboxResult alias, Operation enum, and UnsupportedReason.
• sdk/rust/lib/volume/mod.rs — Volume-related API that emits VolumeNotFound, VolumeAlreadyExists, and Unsupported.
• sdk/rust/lib/snapshot/mod.rs — Snapshot creation, verification, and migration logic that emits Snapshot* errors.
• sdk/rust/lib/setup/windows.rs — Windows host prerequisite errors (WindowsHostSetup).
• sdk/rust/lib/setup/linux.rs — Linux-specific host setup errors (Nix).
• sdk/rust/lib/agent.rs — Agent client errors (AgentClient).
• 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.
• 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<T>, 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}