QSPI address too large to be represented with the given…

Error message

QSPI address too large to be represented with the given address size

What it means

The address value supplied needs more bits than transaction.address_size declares (8, 16, 24, or 32 bits), so it cannot be transmitted within that address size field. The library panics to prevent silent truncation of the address on the bus.

Solutions

Increase transaction.address_size (e.g. AddressSize::_32Bit) to fit the address value.
Compute the address within the declared size, or derive address_size from the device's addressing mode (3-byte vs 4-byte command set).

Example fix

// before
let t = TransferConfig::new(cmd, QspiWidth::SING, Some(0x0200_0000), QspiWidth::SING, QspiWidth::SING).with_address_size(AddressSize::_24Bit);
// after
let t = TransferConfig::new(cmd, QspiWidth::SING, Some(0x0200_0000), QspiWidth::SING, QspiWidth::SING).with_address_size(AddressSize::_32Bit);

Defensive patterns

Strategy: validation

Validate before calling

fn address_fits_size(address: u32, size: AddressSize) -> bool {
    (u32::BITS - address.leading_zeros()) as usize <= size.bit_width()
}

Prevention

Pick address_size from the flash device's addressing mode (3- vs 4-byte).
Add an assert when building configs with large addresses.
Watch for offset overflow when addressing >16 MB with 24-bit sizes.

When it happens

Trigger: Passing an address >= 2^address_size bits, e.g. Some(0x01FF_FFFF) with AddressSize::_24Bit, through blocking_read/blocking_write/setup_auto_poll/setup_command.

Common situations: Using 24-bit addressing with a flash device whose capacity requires 32-bit (4-byte) addresses; overflowing byte-offset math when addressing beyond 16 MB; reusing a fixed AddressSize across differently sized flash chips.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at embassy-stm32/src/qspi/mod.rs:375

    }

    fn setup_command(&mut self, transaction: TransferConfig) {
        #[cfg(not(stm32h7))]
        T::REGS.cr().modify(|v| v.set_dmaen(false));

        self.setup_transaction(QspiMode::IndirectWrite, &transaction, None);
    }

    fn setup_transaction(&mut self, fmode: QspiMode, transaction: &TransferConfig, data_len: Option<usize>) {
        self.assert_transfer_widths(transaction);

        match (transaction.address, transaction.awidth) {
            (Some(_), QspiWidth::NONE) => panic!("QSPI address can't be sent with an address width of NONE"),
            (Some(address), _) => {
                // u32::bit_width was only stabilized in 1.97
                let address_bit_width = u32::BITS - address.leading_zeros();
                if address_bit_width > transaction.address_size.bit_width() as u32 {
                    panic!("QSPI address too large to be represented with the given address size");
                }
            }
            (None, QspiWidth::NONE) => {}
            (None, _) => panic!("QSPI address is not set, so the address width should be NONE"),
        }

        match (data_len, transaction.dwidth) {
            (Some(0), _) => panic!("QSPI data must be at least one byte"),
            (Some(_), QspiWidth::NONE) => panic!("QSPI data can't be sent with a data width of NONE"),
            (Some(_), _) => {}
            (None, QspiWidth::NONE) => {}
            (None, _) => panic!("QSPI data is empty, so the data width should be NONE"),
        }

        T::REGS.fcr().modify(|v| {
            v.set_csmf(true);
            v.set_ctcf(true);
            v.set_ctef(true);

View on GitHub (pinned to 463a07b963)