hyperlight_host/

error.rs

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025 The Hyperlight Authors.

use std::array::TryFromSliceError;
use std::cell::{BorrowError, BorrowMutError};
use std::convert::Infallible;
use std::error::Error;
use std::num::TryFromIntError;
use std::string::FromUtf8Error;
use std::sync::{MutexGuard, PoisonError};
use std::time::SystemTimeError;

#[cfg(target_os = "windows")]
use crossbeam_channel::{RecvError, SendError};
use flatbuffers::InvalidFlatbuffer;
use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterValue, ReturnValue};
use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
use thiserror::Error;

use crate::hypervisor::hyperlight_vm::HyperlightVmError;
#[cfg(target_os = "windows")]
use crate::hypervisor::wrappers::HandleWrapper;
use crate::mem::memory_region::MemoryRegionFlags;
use crate::mem::ptr::RawPtr;

/// The error type for Hyperlight operations
#[derive(Error, Debug)]
pub enum HyperlightError {
    /// Anyhow error
    #[error("Anyhow Error was returned: {0}")]
    AnyhowError(#[from] anyhow::Error),

    /// Checked Add Overflow
    #[error("Couldn't add offset to base address. Offset: {0}, Base Address: {1}")]
    CheckedAddOverflow(u64, u64),

    /// Cross beam channel receive error
    #[error("{0:?}")]
    #[cfg(target_os = "windows")]
    CrossBeamReceiveError(#[from] RecvError),

    /// Cross beam channel send error
    #[error("{0:?}")]
    #[cfg(target_os = "windows")]
    CrossBeamSendError(#[from] SendError<HandleWrapper>),

    /// CString conversion error
    #[error("Error converting CString {0:?}")]
    CStringConversionError(#[from] std::ffi::NulError),

    /// A generic error with a message
    #[error("{0}")]
    Error(String),

    /// Execution violation
    #[error("Non-executable address {0:#x} tried to be executed")]
    ExecutionAccessViolation(u64),

    /// Guest execution was cancelled by the host
    #[error("Execution was cancelled by the host.")]
    ExecutionCanceledByHost(),

    /// Accessing the value of a flatbuffer parameter failed
    #[error("Failed to get a value from flat buffer parameter")]
    FailedToGetValueFromParameter(),

    ///Field Name not found in decoded GuestLogData
    #[error("Field Name {0} not found in decoded GuestLogData")]
    FieldIsMissingInGuestLogData(String),

    /// Guest aborted during outb
    #[error("Guest aborted: {0} {1}")]
    GuestAborted(u8, String),

    /// Guest call resulted in error in guest
    #[error("Guest error occurred {0:?}: {1}")]
    GuestError(ErrorCode, String),

    /// An attempt to cancel guest execution failed because it is hanging on a host function call
    #[error("Guest execution hung on the execution of a host function call")]
    GuestExecutionHungOnHostFunctionCall(),

    /// Guest call already in progress
    #[error("Guest call is already in progress")]
    GuestFunctionCallAlreadyInProgress(),

    /// The given type is not supported by the guest interface.
    #[error("Unsupported type: {0}")]
    GuestInterfaceUnsupportedType(String),

    /// The guest binary was built with a different hyperlight-guest-bin version than the host expects.
    /// Hyperlight currently provides no backwards compatibility guarantees for guest binaries,
    /// so the guest and host versions must match exactly. This might change in the future.
    #[error(
        "Guest binary was built with hyperlight-guest-bin {guest_bin_version}, \
         but the host is running hyperlight {host_version}"
    )]
    GuestBinVersionMismatch {
        /// Version of hyperlight-guest-bin the guest was compiled against.
        guest_bin_version: String,
        /// Version of hyperlight-host.
        host_version: String,
    },

    /// A Host function was called by the guest but it was not registered.
    #[error("HostFunction {0} was not found")]
    HostFunctionNotFound(String),

    /// Hyperlight VM error.
    ///
    /// **Note:** This error variant is considered internal and its structure is not stable.
    /// It may change between versions without notice. Users should not rely on this.
    #[doc(hidden)]
    #[error("Internal Hyperlight VM error: {0}")]
    HyperlightVmError(#[from] HyperlightVmError),

    /// Reading Writing or Seeking data failed.
    #[error("Reading Writing or Seeking data failed {0:?}")]
    IOError(#[from] std::io::Error),

    /// Failed to convert to Integer
    #[error("Failed To Convert Size to usize")]
    IntConversionFailure(#[from] TryFromIntError),

    /// The flatbuffer is invalid
    #[error("The flatbuffer is invalid")]
    InvalidFlatBuffer(#[from] InvalidFlatbuffer),

    /// Conversion of str to Json failed
    #[error("Conversion of str data to json failed")]
    JsonConversionFailure(#[from] serde_json::Error),

    /// An attempt to get a lock from a Mutex failed.
    #[error("Unable to lock resource")]
    LockAttemptFailed(String),

    /// Memory Access Violation at the given address. The access type and memory region flags are provided.
    #[error("Memory Access Violation at address {0:#x} of type {1}, but memory is marked as {2}")]
    MemoryAccessViolation(u64, MemoryRegionFlags, MemoryRegionFlags),

    /// The memory request exceeds the maximum size allowed
    #[error("Memory requested {0} exceeds maximum size allowed {1}")]
    MemoryRequestTooBig(usize, usize),

    /// The memory request is too small to contain everything that is
    /// required
    #[error("Memory requested {0} is less than the minimum size allowed {1}")]
    MemoryRequestTooSmall(usize, usize),

    /// Metric Not Found.
    #[error("Metric Not Found {0:?}.")]
    MetricNotFound(&'static str),

    /// No Hypervisor was found for Sandbox.
    #[error("No Hypervisor was found for Sandbox")]
    NoHypervisorFound(),

    /// Restore_state called with no valid snapshot
    #[error("Restore_state called with no valid snapshot")]
    NoMemorySnapshot,

    /// Failed to get value from parameter value
    #[error("Failed To Convert Parameter Value {0:?} to {1:?}")]
    ParameterValueConversionFailure(ParameterValue, &'static str),

    /// a failure occurred processing a PE file
    #[error("Failure processing PE File {0:?}")]
    PEFileProcessingFailure(#[from] goblin::error::Error),

    /// The sandbox becomes **poisoned** when the guest is not run to completion, leaving it in
    /// an inconsistent state that could compromise memory safety, data integrity, or security.
    ///
    /// ### When Does Poisoning Occur?
    ///
    /// Poisoning happens when guest execution is interrupted before normal completion:
    ///
    /// - **Guest panics or aborts** - When a guest function panics, crashes, or calls `abort()`,
    ///   the normal cleanup and unwinding process is interrupted
    /// - **Invalid memory access** - Attempts to read/write/execute memory outside allowed regions
    /// - **Stack overflow** - Guest exhausts its stack space during execution
    /// - **Heap exhaustion** - Guest runs out of heap memory
    /// - **Host-initiated cancellation** - Calling [`InterruptHandle::kill()`] to forcefully
    ///   terminate an in-progress guest function
    ///
    /// ## Recovery
    ///
    /// Use [`crate::MultiUseSandbox::restore()`] to recover from a poisoned sandbox.
    #[error("The sandbox was poisoned")]
    PoisonedSandbox,

    /// The sandbox cannot safely perform further operations and must be discarded.
    #[error("The sandbox is unrecoverable and must be discarded")]
    UnrecoverableSandbox,

    /// Raw pointer is less than base address
    #[error("Raw pointer ({0:?}) was less than the base address ({1})")]
    RawPointerLessThanBaseAddress(RawPtr, u64),

    /// RefCell borrow failed
    #[error("RefCell borrow failed")]
    RefCellBorrowFailed(#[from] BorrowError),

    /// RefCell mut borrow failed
    #[error("RefCell mut borrow failed")]
    RefCellMutBorrowFailed(#[from] BorrowMutError),

    /// Failed to get value from return value
    #[error("Failed To Convert Return Value {0:?} to {1:?}")]
    ReturnValueConversionFailure(ReturnValue, &'static str),

    /// Error creating or operating on memory shared with the guest
    #[error("Failed to execute shared memory operation: {0}")]
    SharedMemory(#[from] crate::mem::shared_mem::SharedMemoryError),
    /// Tried to restore a snapshot into a sandbox whose registered
    /// host functions do not satisfy the snapshot's required set.
    #[error(
        "Snapshot host function mismatch: missing=[{}], signature mismatches=[{}]",
        missing.join(", "),
        signature_mismatches.join("; ")
    )]
    SnapshotHostFunctionMismatch {
        /// Functions that are required by the snapshot but not present in the target sandbox.
        missing: Vec<String>,
        /// Human-readable descriptions of functions whose signatures
        /// disagree between the snapshot and the target sandbox.
        signature_mismatches: Vec<String>,
    },

    /// SystemTimeError
    #[error("SystemTimeError {0:?}")]
    SystemTimeError(#[from] SystemTimeError),

    /// Error occurred converting a slice to an array
    #[error("TryFromSliceError {0:?}")]
    TryFromSliceError(#[from] TryFromSliceError),

    /// A function was called with an incorrect number of arguments
    #[error("The number of arguments to the function is wrong: got {0:?} expected {1:?}")]
    UnexpectedNoOfArguments(usize, usize),

    /// The parameter value type is unexpected
    #[error("The parameter value type is unexpected got {0:?} expected {1:?}")]
    UnexpectedParameterValueType(ParameterValue, String),

    /// The return value type is unexpected
    #[error("The return value type is unexpected got {0:?} expected {1:?}")]
    UnexpectedReturnValueType(ReturnValue, String),

    /// Slice conversion to UTF8 failed
    #[error("String Conversion of UTF8 data to str failed")]
    UTF8StringConversionFailure(#[from] FromUtf8Error),

    /// The capacity of the vector is incorrect
    #[error(
        "The capacity of the vector is incorrect. Capacity: {0}, Length: {1}, FlatBuffer Size: {2}"
    )]
    VectorCapacityIncorrect(usize, usize, i32),

    /// vmm sys Error Occurred
    #[error("vmm sys Error {0:?}")]
    #[cfg(target_os = "linux")]
    VmmSysError(vmm_sys_util::errno::Error),

    /// Windows Error
    #[cfg(target_os = "windows")]
    #[error("Windows API Error Result {0:?}")]
    WindowsAPIError(#[from] windows_result::Error),
}

impl From<Infallible> for HyperlightError {
    fn from(_: Infallible) -> Self {
        "Impossible as this is an infallible error".into()
    }
}

impl From<&str> for HyperlightError {
    fn from(s: &str) -> Self {
        HyperlightError::Error(s.to_string())
    }
}

impl<T> From<PoisonError<MutexGuard<'_, T>>> for HyperlightError {
    // Implemented this way rather than passing the error as a source to LockAttemptFailed as that would require
    // Box<dyn Error + Send + Sync> which is not easy to implement for PoisonError<MutexGuard<'_, T>>
    // This is a good enough solution and allows use to use the ? operator on lock() calls
    fn from(e: PoisonError<MutexGuard<'_, T>>) -> Self {
        let source = match e.source() {
            Some(s) => s.to_string(),
            None => String::from(""),
        };
        HyperlightError::LockAttemptFailed(source)
    }
}

impl HyperlightError {
    /// Internal helper to determines if the given error has potential to poison the sandbox.
    ///
    /// Errors that poison the sandbox are those that can leave the sandbox in an inconsistent
    /// state where memory, resources, or data structures may be corrupted or leaked. Usually
    /// due to the guest not running to completion.
    ///
    /// If this method returns `true`, the sandbox will be poisoned and all further operations
    /// will fail until the sandbox is restored from a non-poisoned snapshot using
    /// [`crate::MultiUseSandbox::restore()`].
    pub(crate) fn is_poison_error(&self) -> bool {
        // wildcard _ or matches! not used here purposefully to ensure that new error variants
        // are explicitly considered for poisoning behavior.
        match self {
            // These errors poison the sandbox because they can leave it in an inconsistent state due
            // to the guest not running to completion.
            HyperlightError::GuestAborted(_, _)
            | HyperlightError::ExecutionCanceledByHost()
            | HyperlightError::PoisonedSandbox
            | HyperlightError::ExecutionAccessViolation(_)
            | HyperlightError::MemoryAccessViolation(_, _, _)
            // HyperlightVmError::Restore is already handled manually in restore(), but we mark it
            // as poisoning here too for defense in depth.
            | HyperlightError::HyperlightVmError(HyperlightVmError::Restore(_)) => true,

            // These errors poison the sandbox because they can leave
            // it in an inconsistent state due to snapshot restore
            // failing partway through
            HyperlightError::HyperlightVmError(HyperlightVmError::UpdateRegion(_))
            | HyperlightError::HyperlightVmError(HyperlightVmError::AccessPageTable(_)) => true,

            // HyperlightVmError::DispatchGuestCall may poison the sandbox
            HyperlightError::HyperlightVmError(HyperlightVmError::DispatchGuestCall(e)) => {
                e.is_poison_error()
            }

            // All other errors do not poison the sandbox.
            HyperlightError::AnyhowError(_)
            | HyperlightError::CheckedAddOverflow(_, _)
            | HyperlightError::CStringConversionError(_)
            | HyperlightError::Error(_)
            | HyperlightError::FailedToGetValueFromParameter()
            | HyperlightError::FieldIsMissingInGuestLogData(_)
            | HyperlightError::GuestBinVersionMismatch { .. }
            | HyperlightError::GuestError(_, _)
            | HyperlightError::GuestExecutionHungOnHostFunctionCall()
            | HyperlightError::GuestFunctionCallAlreadyInProgress()
            | HyperlightError::GuestInterfaceUnsupportedType(_)
            | HyperlightError::HostFunctionNotFound(_)
            | HyperlightError::HyperlightVmError(HyperlightVmError::Create(_))
            | HyperlightError::HyperlightVmError(HyperlightVmError::Initialize(_))
            | HyperlightError::HyperlightVmError(HyperlightVmError::MapRegion(_))
            | HyperlightError::HyperlightVmError(HyperlightVmError::UnmapRegion(_))
            | HyperlightError::IOError(_)
            | HyperlightError::IntConversionFailure(_)
            | HyperlightError::InvalidFlatBuffer(_)
            | HyperlightError::JsonConversionFailure(_)
            | HyperlightError::LockAttemptFailed(_)
            | HyperlightError::MemoryRequestTooBig(_, _)
            | HyperlightError::MemoryRequestTooSmall(_, _)
            | HyperlightError::MetricNotFound(_)
            | HyperlightError::NoHypervisorFound()
            | HyperlightError::NoMemorySnapshot
            | HyperlightError::ParameterValueConversionFailure(_, _)
            | HyperlightError::PEFileProcessingFailure(_)
            | HyperlightError::RawPointerLessThanBaseAddress(_, _)
            | HyperlightError::RefCellBorrowFailed(_)
            | HyperlightError::RefCellMutBorrowFailed(_)
            | HyperlightError::ReturnValueConversionFailure(_, _)
            | HyperlightError::SnapshotHostFunctionMismatch { .. }
            | HyperlightError::SystemTimeError(_)
            | HyperlightError::TryFromSliceError(_)
            | HyperlightError::UnexpectedNoOfArguments(_, _)
            | HyperlightError::UnexpectedParameterValueType(_, _)
            | HyperlightError::UnexpectedReturnValueType(_, _)
            | HyperlightError::UnrecoverableSandbox
            | HyperlightError::UTF8StringConversionFailure(_)
            | HyperlightError::VectorCapacityIncorrect(_, _, _)
            | HyperlightError::SharedMemory(_) => false,

            #[cfg(target_os = "windows")]
            HyperlightError::CrossBeamReceiveError(_) => false,
            #[cfg(target_os = "windows")]
            HyperlightError::CrossBeamSendError(_) => false,
            #[cfg(target_os = "windows")]
            HyperlightError::WindowsAPIError(_) => false,
            #[cfg(target_os = "linux")]
            HyperlightError::VmmSysError(_) => false,
        }
    }
}

/// Creates a `HyperlightError::Error` from a string literal or format string
#[macro_export]
macro_rules! new_error {
    ($msg:literal $(,)?) => {{
        let __args = std::format_args!($msg);
        let __err_msg = match __args.as_str() {
            Some(msg) => String::from(msg),
            None => std::format!($msg),
        };
        $crate::HyperlightError::Error(__err_msg)
    }};
    ($fmtstr:expr, $($arg:tt)*) => {{
           let __err_msg = std::format!($fmtstr, $($arg)*);
           $crate::error::HyperlightError::Error(__err_msg)
    }};
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::hypervisor::hyperlight_vm::{
        DispatchGuestCallError, HandleIoError, HyperlightVmError, RunVmError,
    };
    use crate::sandbox::outb::HandleOutbError;

    /// Test that ExecutionCancelledByHost promotes to HyperlightError::ExecutionCanceledByHost
    #[test]
    fn test_promote_execution_cancelled_by_host() {
        let err = DispatchGuestCallError::Run(RunVmError::ExecutionCancelledByHost);
        let (promoted, should_poison) = err.promote();

        assert!(
            should_poison,
            "ExecutionCancelledByHost should poison the sandbox"
        );
        assert!(
            matches!(promoted, HyperlightError::ExecutionCanceledByHost()),
            "Expected HyperlightError::ExecutionCanceledByHost, got {:?}",
            promoted
        );
    }

    /// Test that GuestAborted promotes to HyperlightError::GuestAborted with correct values
    #[test]
    fn test_promote_guest_aborted() {
        let err = DispatchGuestCallError::Run(RunVmError::HandleIo(HandleIoError::Outb(
            HandleOutbError::GuestAborted {
                code: 42,
                message: "test abort".to_string(),
            },
        )));
        let (promoted, should_poison) = err.promote();

        assert!(should_poison, "GuestAborted should poison the sandbox");
        match promoted {
            HyperlightError::GuestAborted(code, msg) => {
                assert_eq!(code, 42);
                assert_eq!(msg, "test abort");
            }
            _ => panic!("Expected HyperlightError::GuestAborted, got {:?}", promoted),
        }
    }

    /// Test that MemoryAccessViolation promotes to HyperlightError::MemoryAccessViolation
    #[test]
    fn test_promote_memory_access_violation() {
        let err = DispatchGuestCallError::Run(RunVmError::MemoryAccessViolation {
            addr: 0xDEADBEEF,
            access_type: MemoryRegionFlags::WRITE,
            region_flags: MemoryRegionFlags::READ,
        });
        let (promoted, should_poison) = err.promote();

        assert!(
            should_poison,
            "MemoryAccessViolation should poison the sandbox"
        );
        match promoted {
            HyperlightError::MemoryAccessViolation(addr, access_type, region_flags) => {
                assert_eq!(addr, 0xDEADBEEF);
                assert_eq!(access_type, MemoryRegionFlags::WRITE);
                assert_eq!(region_flags, MemoryRegionFlags::READ);
            }
            _ => panic!(
                "Expected HyperlightError::MemoryAccessViolation, got {:?}",
                promoted
            ),
        }
    }

    /// Test that non-promoted Run errors are wrapped in HyperlightVmError
    #[test]
    fn test_promote_other_run_errors_wrapped() {
        let err = DispatchGuestCallError::Run(RunVmError::MmioReadUnmapped(0x1000));
        let (promoted, should_poison) = err.promote();

        assert!(should_poison, "Run errors should poison the sandbox");
        assert!(
            matches!(
                promoted,
                HyperlightError::HyperlightVmError(HyperlightVmError::DispatchGuestCall(_))
            ),
            "Expected HyperlightError::HyperlightVmError, got {:?}",
            promoted
        );
    }
}