firecracker-microvm/firecracker · error

bzImage load always yields a setup header

Error message

bzImage load always yields a setup header

What it means

Error "bzImage load always yields a setup header" thrown in firecracker-microvm/firecracker.

Source

Thrown at src/vmm/src/arch/x86_64/mod.rs:542

            debug!("Kernel loaded using {boot_prot}");

            Ok(EntryPoint {
                entry_addr: entry_point_addr,
                protocol: boot_prot,
                setup_header: None,
            })
        }
        // Not an ELF image: fall back to the bzImage loader.
        Err(KernelLoaderError::Elf(ElfError::InvalidElfMagicNumber)) => {
            let bzimage_result =
                BzImageLoader::load(guest_memory, None, &mut kernel_file, highmem_start)
                    .map_err(ConfigurationError::KernelLoader)?;

            // We jump to the 64-bit entry point, which only exists when the
            // image advertises it via XLF_KERNEL_64 (boot protocol >= 2.12).
            let hdr = bzimage_result
                .setup_header
                .expect("bzImage load always yields a setup header");
            if hdr.version < 0x020c || hdr.xloadflags & XLF_KERNEL_64 == 0 {
                return Err(ConfigurationError::BzImageMissing64BitEntry);
            }

            // Enter at the 64-bit entry point (BZIMAGE_64BIT_ENTRY_OFFSET
            // past the load address); the setup header seeds the zero page.
            let entry_addr = bzimage_result
                .kernel_load
                .checked_add(BZIMAGE_64BIT_ENTRY_OFFSET)
                .ok_or(ConfigurationError::KernelLoader(
                    KernelLoaderError::MemoryOverflow,
                ))?;

            debug!("Kernel loaded using {} (bzImage)", BootProtocol::LinuxBoot);

            Ok(EntryPoint {
                entry_addr,
                protocol: BootProtocol::LinuxBoot,

View on GitHub (pinned to 81b38b9dad)

Solutions

1. This indicates a logic error in the bzImage loader; the setup header must always be present after a successful load.
2. Verify the kernel image is a valid bzImage and was not truncated before loading.

When it happens

Trigger: Thrown at src/vmm/src/arch/x86_64/mod.rs:496 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/bdef3bdaa463e2b2. Report an issue: GitHub.