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 dualbank value in the user option bytes or configure embassy to use single-bank config

What it means

This panic fires at flash-driver init time when embassy-stm32 is compiled with the dual-bank cargo feature but the chip's user option bytes say the flash is in single-bank mode. The library checks the hardware's OPTR register against the compile-time configuration because bank layout determines flash sector sizing, erase/write behavior, and memory mapping, and a mismatch would corrupt memory operations silently.

Solutions

Either change the hardware config: set the dualbank bit (nDBANK on many parts) in the user option bytes via STM32CubeProgrammer, STM32CubeIDE, or a bootloader, then power-cycle the chip
Or change the software config: rebuild embassy-stm32 with the single-bank feature (or without the dual-bank feature) instead of dual-bank
Verify with the reference manual which bank mode your exact part number defaults to and pick the matching cargo feature
Note that changing option bytes may erase flash — back up firmware first

Example fix

// before (Cargo.toml)
embassy-stm32 = { version = "0.2", features = ["stm32h743zi", "dual-bank"] }
// after (if the chip option bytes say single-bank)
embassy-stm32 = { version = "0.2", features = ["stm32h743zi", "single-bank"] }

Defensive patterns

Strategy: validation

Validate before calling

// Before enabling flash, read the option bytes yourself and match the cargo feature
let dualbank_hw = pac::FLASH.optr().read().dualbank();
#[cfg(feature = "dual-bank")]
assert!(dualbank_hw, "hardware is single-bank; build with single-bank feature or set nDBANK=0 in option bytes");
#[cfg(feature = "single-bank")]
assert!(!dualbank_hw, "hardware is dual-bank; build with dual-bank feature or change the dualbank option byte");

Prevention

Keep the cargo feature flag and the chip's option-byte configuration in the same board documentation/release script
Verify option bytes with STM32CubeProgrammer after any flashing or bootloader session
Read the part number's reference manual to confirm default bank mode before choosing features
Automate the check: read OPTR at startup and log it before initializing the flash driver

When it happens

Trigger: Calling any flash API (or constructing the flash driver) on an STM32 part whose code path runs check_bank_setup when: (1) the crate was built with feature "dual-bank", and (2) FLASH.optr().read().dualbank() returns false, meaning the option bytes configure single-bank mode.

Common situations: Using an embassy-stm32 feature flag set for a dual-bank variant (e.g. H7/WB) while the board was flashed with option bytes configuring single-bank; reusing a build config from a different board revision; a bootloader or STM32CubeProgrammer session changed the dualbank option byte; switching chip part numbers without updating cargo features.

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/32c5b6f495a35df8. Report an issue: GitHub.

Appendix: source

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

            "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)