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

Error message

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

What it means

On STM32F7, bank configuration is controlled by the N_DBANK bit (0 = dual bank, 1 = single bank). When Embassy is built with the 'single-bank' feature but N_DBANK indicates the hardware is in dual-bank mode, the compile-time flash layout does not match the physical one, so check_bank_setup() panics to prevent incorrect erase/write addressing.

Solutions

Rebuild with the 'dual-bank' feature, or set N_DBANK=1 in the user option bytes (via STM32CubeProgrammer, then power cycle) to make hardware single-bank.
Decide the desired layout first, then keep cargo features and option bytes in lockstep.
Document/CI-check the feature flags that must match each board's option-byte image.

Example fix

// before (Cargo.toml, hardware dual-bank F7)
features = ["stm32f767zi", "single-bank"]
// after
features = ["stm32f767zi", "dual-bank"]
// or set option byte N_DBANK=1 via STM32CubeProgrammer and power cycle

Defensive patterns

Strategy: validation

Validate before calling

fn f7_bank_ok(single_bank_feature: bool, n_dbank: bool) -> bool {
    single_bank_feature == n_dbank // N_DBANK=1 means single bank
}

Prevention

Remember F7 polarity: N_DBANK=1 => single bank, 0 => dual bank
Set option bytes and cargo features together in board bring-up scripts
Power cycle after option-byte changes so they take effect

When it happens

Trigger: Flash initialization on a bank-setup-configurable F7 part built with feature = "single-bank" while FLASH.optcr.N_DBANK == 0 (dual bank).

Common situations: Firmware built for single-bank (e.g. to simplify sector layout) running on boards whose option bytes keep dual-bank enabled from factory; feature/option-byte drift after flashing a different firmware variant.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at embassy-stm32/src/flash/f7.rs:174

        assert_sector(0, 0x0800_0000, SMALL_SECTOR_SIZE, 0x0800_0000);
        assert_sector(0, 0x0800_0000, SMALL_SECTOR_SIZE, 0x0800_7FFF);
        assert_sector(3, 0x0801_8000, SMALL_SECTOR_SIZE, 0x0801_8000);
        assert_sector(3, 0x0801_8000, SMALL_SECTOR_SIZE, 0x0801_FFFF);

        assert_sector(4, 0x0802_0000, MEDIUM_SECTOR_SIZE, 0x0802_0000);
        assert_sector(4, 0x0802_0000, MEDIUM_SECTOR_SIZE, 0x0803_FFFF);

        assert_sector(5, 0x0804_0000, LARGE_SECTOR_SIZE, 0x0804_0000);
        assert_sector(5, 0x0804_0000, LARGE_SECTOR_SIZE, 0x0807_FFFF);
        assert_sector(7, 0x080C_0000, LARGE_SECTOR_SIZE, 0x080C_0000);
        assert_sector(7, 0x080C_0000, LARGE_SECTOR_SIZE, 0x080F_FFFF);
    }
}

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

View on GitHub (pinned to 463a07b963)