embassy-rs/embassy · critical

Embassy is configured as dual-bank, but the hardware is…

Error message

Embassy is configured as dual-bank, but the hardware is running in single-bank mode. Change the hardware by changing the dbank value in the user option bytes or configure embassy to use single-bank config

What it means

This panic comes from check_bank_setup in embassy-stm32's flash driver for STM32L5 devices. The 'dual-bank' cargo feature was enabled, but the OPTR register's DBANK bit indicates single-bank mode. Embassy panics at init because a dual-bank driver layout would address flash incorrectly on single-bank L5 hardware.

Solutions

  1. Change your embassy-stm32 feature from "dual-bank" to "single-bank" in Cargo.toml to match DBANK=0 hardware
  2. Set the DBANK option bit to 1 in the user option bytes (STM32CubeProgrammer or probe-rs) if dual-bank is required; back up flash first as this re-partitions the flash layout
  3. Power-cycle and verify OPTR.DBANK via debugger before reflashing firmware

Example fix

// before (Cargo.toml)
embassy-stm32 = { version = "...", features = ["stm32l552xx", "dual-bank"] }
// after
embassy-stm32 = { version = "...", features = ["stm32l552xx", "single-bank"] }
Defensive patterns

Strategy: validation

Validate before calling

// Rust, before initializing the flash driver
let optr = unsafe { pac::FLASH.optr().read() };
assert_eq!(optr.dbank(), cfg!(feature = "dual-bank"),
    "embassy flash bank feature must match OPTR.DBANK");

Prevention

When it happens

Trigger: Building with feature = "dual-bank" for an STM32L5 target whose user option bytes have DBANK=0; panic fires at flash init when check_bank_setup evaluates !pac::FLASH.optr().read().dbank().

Common situations: Option bytes erased/reset to defaults (DBANK cleared) after a mass erase while the build kept dual-bank features; features copied from an L5 project with different option-byte settings; board swap without updating config.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of embassy-rs/embassy@463a07b963 (2026-09-10). Data as JSON: /api/errors/28d1553bde66792d. Report an issue: GitHub.

Appendix: source

Thrown at embassy-stm32/src/flash/l.rs:424

                if nssr.nspgserr() {
                    return Err(Error::Seq);
                }

                return Ok(());
            }
        }
    }
}

#[cfg(all(bank_setup_configurable, flash_l5))]
pub(crate) fn check_bank_setup() {
    if cfg!(feature = "single-bank") && pac::FLASH.optr().read().dbank() {
        panic!(
            "Embassy is configured as single-bank, but the hardware is running in dual-bank mode. Change the hardware by changing the dbank value in the user option bytes or configure embassy to use dual-bank config"
        );
    }
    if cfg!(feature = "dual-bank") && !pac::FLASH.optr().read().dbank() {
        panic!(
            "Embassy is configured as dual-bank, but the hardware is running in single-bank mode. Change the hardware by changing the dbank value in the user option bytes or configure embassy to use single-bank config"
        );
    }
}

#[cfg(all(bank_setup_configurable, flash_l4))]
pub(crate) fn check_bank_setup() {
    if cfg!(feature = "single-bank") && pac::FLASH.optr().read().dualbank() {
        panic!(
            "Embassy is configured as single-bank, but the hardware is running in dual-bank mode. Change the hardware by changing the dualbank value in the user option bytes or configure embassy to use dual-bank config"
        );
    }
    if cfg!(feature = "dual-bank") && !pac::FLASH.optr().read().dualbank() {
        panic!(
            "Embassy is configured as dual-bank, but the hardware is running in single-bank mode. Change the hardware by changing the dualbank value in the user option bytes or configure embassy to use single-bank config"
        );
    }
}

View on GitHub (pinned to 463a07b963)