firecracker-microvm/firecracker · error

Timed out waiting for vCPU thread '{name}' to exit

Error message

Timed out waiting for vCPU thread '{name}' to exit

What it means

Error "Timed out waiting for vCPU thread '{name}' to exit" thrown in firecracker-microvm/firecracker.

Source

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

    }
}

// Wait for the Vcpu thread to finish execution
impl Drop for VcpuHandle {
    fn drop(&mut self) {
        // The vCPU thread owns the response sender, so the channel disconnects
        // once it exits. Wait for that disconnect (draining any stale responses)
        // with a timeout rather than joining unconditionally, so a thread that
        // never finished (e.g. a missed Finish event) fails fast instead of
        // hanging teardown forever.
        let thread = self.vcpu_thread.take().unwrap();
        loop {
            match self.response_receiver.recv_timeout(VCPU_JOIN_TIMEOUT) {
                // Sender dropped: the thread has exited.
                Err(RecvTimeoutError::Disconnected) => break,
                Err(RecvTimeoutError::Timeout) => {
                    let name = thread.thread().name().unwrap_or("<unnamed>");
                    panic!("Timed out waiting for vCPU thread '{name}' to exit")
                }
                // Unexpected: a response was still queued at teardown. Discard
                // it and keep waiting for the thread to exit.
                Ok(response) => {
                    warn!("Discarding unexpected vCPU response during teardown: {response:?}");
                }
            }
        }
        thread.join().unwrap();
    }
}

/// Vcpu emulation state.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
pub enum VcpuEmulation {
    /// Handled.
    Handled,
    /// Interrupted.

View on GitHub (pinned to 81b38b9dad)

Solutions

1. Investigate why the named vCPU thread did not exit; check for a stuck KVM_RUN or guest hang.
2. Fix the hang rather than increasing the shutdown timeout, unless the vCPU is provably making progress.

When it happens

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

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

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