{"record":{"id":"4a87a557ee8ab40b","repo":"embassy-rs/embassy","slug":"failed-to-load-pio-program","errorCode":null,"errorMessage":"Failed to load PIO program: {:?}","messagePattern":"Failed to load PIO program: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"embassy-rp/src/pio/mod.rs","lineNumber":1216,"sourceCode":"#[derive(Clone, Copy, PartialEq, Eq, Debug)]\n#[cfg_attr(feature = \"defmt\", derive(defmt::Format))]\npub enum LoadError {\n    /// Insufficient consecutive free instruction space to load program.\n    InsufficientSpace,\n    /// Loading the program would overwrite an instruction address already\n    /// used by another program.\n    AddressInUse(usize),\n}\n\nimpl<'d, PIO: Instance> Common<'d, PIO> {\n    /// Load a PIO program. This will automatically relocate the program to\n    /// an available chunk of free instruction memory if the program origin\n    /// was not explicitly specified, otherwise it will attempt to load the\n    /// program only at its origin.\n    pub fn load_program<const SIZE: usize>(&mut self, prog: &Program<SIZE>) -> LoadedProgram<'d, PIO> {\n        match self.try_load_program(prog) {\n            Ok(r) => r,\n            Err(e) => panic!(\"Failed to load PIO program: {:?}\", e),\n        }\n    }\n\n    /// Load a PIO program. This will automatically relocate the program to\n    /// an available chunk of free instruction memory if the program origin\n    /// was not explicitly specified, otherwise it will attempt to load the\n    /// program only at its origin.\n    pub fn try_load_program<const SIZE: usize>(\n        &mut self,\n        prog: &Program<SIZE>,\n    ) -> Result<LoadedProgram<'d, PIO>, LoadError> {\n        match prog.origin {\n            Some(origin) => self.try_load_program_at(prog, origin).map_err(LoadError::AddressInUse),\n            None => {\n                // naively search for free space, allowing wraparound since\n                // PIO does support that. with only 32 instruction slots it\n                // doesn't make much sense to do anything more fancy.\n                let mut origin = 0;","sourceCodeStart":1198,"sourceCodeEnd":1234,"githubUrl":"https://github.com/embassy-rs/embassy/blob/463a07b963419a1bfe61d5d597c44acb810afb8b/embassy-rp/src/pio/mod.rs#L1198-L1234","documentation":"`PIO::load_program` is the panicking wrapper around `try_load_program`. It panics when the PIO instruction memory cannot accommodate the program at any (or the requested) origin — e.g. insufficient free instruction slots, or the program's fixed origin is already occupied/out of range.","triggerScenarios":"Loading a program whose SIZE exceeds free instruction memory; loading two programs that overlap; specifying `origin` where memory is already used; on RP2040 only 32 instruction slots exist per PIO so multiple large programs overflow.","commonSituations":"Loading a second PIO program into the same block without unloading the first; a program with a hard-coded origin conflicting with an auto-placed program; using a PIO block that cyw43 or another driver already claimed.","solutions":["Switch to `try_load_program` and handle the LoadError instead of panicking","Unload existing programs or use a different PIO block with free instruction memory","Reduce program size or remove an explicit `origin` so relocation can find space","Verify which PIO instance is shared and whether another driver already loaded a program"],"exampleFix":"// before\nlet loaded = pio.load_program(&prog);\n// after\nlet loaded = match pio.try_load_program(&prog) {\n    Ok(l) => l,\n    Err(e) => defmt::error!(\"pio load failed: {:?}\", e),\n};","handlingStrategy":"try-catch","validationCode":"// ensure program fits: count used instruction memory first\nassert!(prog.code.len() <= 32, \"program too large for PIO instr mem\");","typeGuard":null,"tryCatchPattern":"match pio.try_load_program(&prog) {\n    Ok(l) => l,\n    Err(LoadError::InsufficientFreeProgramMemory) => defmt::error!(\"PIO full\"),\n    Err(e) => defmt::error!(\"load failed: {:?}\", e),\n}","preventionTips":["Use try_load_program in library/driver code; reserve load_program for examples","Track which programs occupy each PIO block","Avoid fixed origins unless relocation is impossible for your timing requirements"],"tags":["pio","embedded","memory","rust"],"backgroundTag":"resource-not-found","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"}