firecracker-microvm/firecracker · error

Failed to register vcpu signal handler

Error message

Failed to register vcpu signal handler

What it means

Error "Failed to register vcpu signal handler" thrown in firecracker-microvm/firecracker.

Source

Thrown at src/vmm/src/vstate/vcpu.rs:131

    /// The vCPU is executing guest code via `KVM_RUN`.
    Running,
    /// The vCPU is paused, waiting for events.
    Paused,
    /// The vCPU thread's run loop has finished; the thread will exit.
    Finished,
}

impl Vcpu {
    /// Registers a signal handler which kicks the vcpu running on the current thread, if there is
    /// one.
    fn register_kick_signal_handler(&mut self) {
        extern "C" fn handle_signal(_: c_int, _: *mut siginfo_t, _: *mut c_void) {
            // We write to the immediate_exit from other thread, so make sure the read in the
            // KVM_RUN sees the up to date value
            fence(Ordering::Acquire);
        }
        register_signal_handler(sigrtmin() + VCPU_RTSIG_OFFSET, handle_signal)
            .expect("Failed to register vcpu signal handler");
    }

    /// Constructs a new VCPU for `vm`.
    ///
    /// # Arguments
    ///
    /// * `index` - Represents the 0-based CPU index between [0, max vcpus).
    /// * `vm` - The vm to which this vcpu will get attached.
    /// * `exit_evt` - An `EventFd` that will be written into when this vcpu exits.
    pub fn new(index: u8, vm: &KvmVm, exit_evt: EventFd) -> Result<Self, VcpuError> {
        let (event_sender, event_receiver) = channel();
        let (response_sender, response_receiver) = channel();
        let kvm_vcpu = KvmVcpu::new(index, vm).unwrap();

        Ok(Vcpu {
            exit_evt,
            event_receiver,
            event_sender: Some(event_sender),

View on GitHub (pinned to 81b38b9dad)

Solutions

1. Check that signal-handler registration is permitted (not blocked by seccomp or rlimit) before starting vCPUs.
2. Inspect the underlying OS error from sigaction for the precise cause.

When it happens

Trigger: Thrown at src/vmm/src/vstate/vcpu.rs:131 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of firecracker-microvm/firecracker@81b38b9dad (2026-08-19). Data as JSON: /api/errors/152768ae72a3a094. Report an issue: GitHub.