firecracker-microvm/firecracker · error

Bus ranges and devices out of sync

Error message

Bus ranges and devices out of sync

What it means

Error "Bus ranges and devices out of sync" thrown in firecracker-microvm/firecracker.

Source

Thrown at src/vmm/src/vstate/bus.rs:201

    // The ranges read lock is only held for resolving the address and is
    // dropped before performing the operation on the device.
    fn with_device<T>(
        &self,
        addr: u64,
        f: impl FnOnce(&mut dyn BusDevice, u64, u64) -> T,
    ) -> Result<T, BusError> {
        let devices = self.devices.read().unwrap();
        let (base, slot) = {
            let ranges = self.ranges.read().unwrap();
            match ranges.range(..=BusRange::new(addr, 1).unwrap()).next_back() {
                Some((range, &slot)) if addr <= range.end() => (range.base(), slot),
                _ => return Err(BusError::MissingAddressRange),
            }
        };

        let device = devices
            .get(slot)
            .expect("Bus ranges and devices out of sync");

        let Some(device) = device.upgrade() else {
            return Err(BusError::MissingAddressRange);
        };

        let mut locked = device.lock().unwrap();
        let offset = addr - base;
        Ok(f(&mut *locked, base, offset))
    }

    /// Relocate an existing device mapping from `old_base` to `new_base`.
    /// Only the `ranges` lock is taken, not the `devices` lock.
    pub fn move_range(&self, old_base: u64, new_base: u64, len: u64) -> Result<(), BusError> {
        let old_range = BusRange::new(old_base, len)?;
        let new_range = BusRange::new(new_base, len)?;

        let mut ranges = self.ranges.write().unwrap();

View on GitHub (pinned to 0a745def42)

Solutions

1. Keep the bus range list and device list updates in a single atomic operation so they cannot diverge.
2. Check the bus insert/remove logic for a path that updates one list without the other.

When it happens

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

Common situations: See trigger scenarios.

AI-assisted analysis of firecracker-microvm/firecracker@0a745def42 (2026-08-19). Data as JSON: /api/errors/1f60050fb9520db5. Report an issue: GitHub.