{"record":{"id":"14c0df512fe15c9a","repo":"embassy-rs/embassy","slug":"boot-prepare-error-14c0df","errorCode":null,"errorMessage":"Boot prepare error","messagePattern":"Boot prepare error","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"embassy-boot-stm32/src/lib.rs","lineNumber":29,"sourceCode":"use embedded_storage::nor_flash::NorFlash;\n\n/// A bootloader for STM32 devices.\npub struct BootLoader {\n    /// The reported state of the bootloader after preparing for boot\n    pub state: State,\n}\n\nimpl BootLoader {\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, const BUFFER_SIZE: usize>(\n        config: BootLoaderConfig<ACTIVE, DFU, STATE>,\n    ) -> Self {\n        if let Ok(loader) = Self::try_prepare::<ACTIVE, DFU, STATE, BUFFER_SIZE>(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, const BUFFER_SIZE: usize>(\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 { state })\n    }\n\n    /// Boots the application.\n    ///\n    /// # Safety\n    ///\n    /// This modifies the stack pointer and reset vector and will run code placed in the active partition.","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/embassy-rs/embassy/blob/463a07b963419a1bfe61d5d597c44acb810afb8b/embassy-boot-stm32/src/lib.rs#L11-L47","documentation":"embassy-boot-stm32's `prepare` panics with \"Boot prepare error\" if `try_prepare` fails. try_prepare inspects the bootloader state and performs required pre-boot actions (firmware swap) across the ACTIVE/DFU/STATE NorFlash partitions, optionally using an aligned BUFFER. Any flash error or invalid state triggers this panic, routed via defmt instead of expect.","triggerScenarios":"Calling `BootLoader::prepare(BootLoaderConfig { .. })` when try_prepare returns Err: invalid/corrupted state magic in the STATE partition, NorFlash errors on any partition, or a BUFFER_SIZE too small / misconfigured partitions on STM32 internal flash.","commonSituations":"First boot after OTA image write with stale state; partition layout in BootLoaderConfig not matching the flash bank layout; buffer size smaller than the flash write granularity.","solutions":["Use `BootLoader::try_prepare::<ACTIVE, DFU, STATE, BUFFER_SIZE>` and handle Err explicitly","Verify partition offsets/sizes against the STM32 flash bank layout and linker script","Ensure BUFFER_SIZE meets the required write-granularity for your STM32 family","Erase or rewrite the STATE partition to a valid state on provisioning"],"exampleFix":"// before\nlet loader = BootLoader::prepare(config);\n// after\nlet loader = match BootLoader::try_prepare::<ACTIVE, DFU, STATE, BUFFER_SIZE>(config) {\n    Ok(l) => l,\n    Err(e) => { defmt::error!(\"prepare failed: {:?}\", e); recover(); }\n};","handlingStrategy":"try-catch","validationCode":"const BUFFER_SIZE: usize = 4096; // must be >= flash write granularity\nfn partitions_ok(p: [(u32, u32); 3]) -> bool {\n    p.iter().all(|&(off, len)| off % 2048 == 0 && len % 2048 == 0)\n}","typeGuard":null,"tryCatchPattern":"match BootLoader::try_prepare::<ACTIVE, DFU, STATE, BUFFER_SIZE>(config) {\n    Ok(l) => l,\n    Err(e) => { defmt::error!(\"prepare failed: {:?}\", e); boot_recovery_image(); }\n};","preventionTips":["Use try_prepare so flash errors are observable instead of a panic","Match BUFFER_SIZE to the STM32 family's write granularity (e.g. 8 bytes on F4, 64+ on others)","Keep partition constants generated from one source of truth shared with the linker script","Provision the STATE partition during factory flashing"],"tags":["embedded","bootloader","firmware-update","panic","stm32"],"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"}