{"record":{"id":"a635713284e2eb50","repo":"embassy-rs/embassy","slug":"boot-prepare-error","errorCode":null,"errorMessage":"Boot prepare error","messagePattern":"Boot prepare error","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"embassy-boot-nrf/src/lib.rs","lineNumber":28,"sourceCode":"};\nuse embassy_nrf::nvmc::PAGE_SIZE;\nuse embassy_nrf::{Peri, wdt};\nuse embedded_storage::nor_flash::{ErrorType, NorFlash, ReadNorFlash};\n\n/// A bootloader for nRF devices.\npub struct BootLoader<const BUFFER_SIZE: usize = PAGE_SIZE>;\n\nimpl<const BUFFER_SIZE: usize> BootLoader<BUFFER_SIZE> {\n    /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware\n    pub fn prepare<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash>(\n        config: BootLoaderConfig<ACTIVE, DFU, STATE>,\n    ) -> Self {\n        if let Ok(loader) = Self::try_prepare::<ACTIVE, DFU, STATE>(config) {\n            loader\n        } else {\n            // Use explicit panic instead of .expect() to ensure this gets routed via defmt/etc.\n            // properly\n            panic!(\"Boot prepare error\")\n        }\n    }\n\n    /// Inspect the bootloader state and perform actions required before booting, such as swapping firmware\n    pub fn try_prepare<ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash>(\n        config: BootLoaderConfig<ACTIVE, DFU, STATE>,\n    ) -> Result<Self, BootError> {\n        let mut aligned_buf = AlignedBuffer([0; BUFFER_SIZE]);\n        let mut boot = embassy_boot::BootLoader::new(config);\n        let _state = boot.prepare_boot(aligned_buf.as_mut())?;\n        Ok(Self)\n    }\n\n    /// Boots the application without softdevice mechanisms.\n    ///\n    /// # Safety\n    ///\n    /// This modifies the stack pointer and reset vector and will run code placed in the active partition.","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/embassy-rs/embassy/blob/463a07b963419a1bfe61d5d597c44acb810afb8b/embassy-boot-nrf/src/lib.rs#L10-L46","documentation":"embassy-boot-nrf's `prepare` calls `try_prepare` and panics with \"Boot prepare error\" if the bootloader state cannot be processed. `try_prepare` fails when inspecting or mutating the boot swap state (active/DFU/state flash partitions) returns an error, e.g. unreadable or misaligned flash. The panic exists so the failure is routed through defmt logging rather than a hidden expect.","triggerScenarios":"Constructing a `BootLoader` via `BootLoader::prepare(BootLoaderConfig { .. })` at startup when `try_prepare` returns Err: bad state magic/corrupted state partition, NorFlash read/write/erase errors on the active, DFU, or STATE partitions, or misconfigured partition boundaries.","commonSituations":"First boot after flashing a fresh DFU partition with garbage state; state partition not erased before first use; wrong partition sizes/offsets in BootLoaderConfig; flash driver erroring due to wrong memory-mapped region on nRF.","solutions":["Call `BootLoader::try_prepare` instead of `prepare` and handle the Err case explicitly","Verify the ACTIVE/DFU/STATE partition offsets and sizes match the linker memory layout","Erase/initialize the STATE partition to a known-good value on first boot","Check the underlying NorFlash error from try_prepare to identify the failing partition"],"exampleFix":"// before\nlet loader = BootLoader::prepare(config);\n// after\nlet loader = match BootLoader::try_prepare::<ACTIVE, DFU, STATE>(config) {\n    Ok(l) => l,\n    Err(e) => { defmt::error!(\"boot prepare failed: {:?}\", e); fallback_boot(); }\n};","handlingStrategy":"try-catch","validationCode":"fn partitions_sane(active: (u32, u32), dfu: (u32, u32), state: (u32, u32)) -> bool {\n    let ok = |(off, len): (u32, u32)| off % 4096 == 0 && len % 4096 == 0;\n    ok(active) && ok(dfu) && ok(state)\n}","typeGuard":null,"tryCatchPattern":"match BootLoader::try_prepare::<ACTIVE, DFU, STATE>(config) {\n    Ok(loader) => loader,\n    Err(e) => { defmt::error!(\"boot prepare: {:?}\", e); enter_safe_boot(); }\n};","preventionTips":["Prefer try_prepare over prepare in production boot code","Keep ACTIVE/DFU/STATE partitions aligned with the linker script","Erase the STATE partition during provisioning/first boot","Log the underlying flash error from try_prepare during development"],"tags":["embedded","bootloader","firmware-update","panic","nrf"],"backgroundTag":"boot-prepare-error","analyzedSha":"463a07b963419a1bfe61d5d597c44acb810afb8b","analyzedAt":"2026-09-10T13:38:26.660Z","contentChangedAt":"2026-09-10T13:38:26.660Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}