STM32 linker "region `FLASH' overflowed" in CI

By Kaveh Alemi·Latchkey

The linker placed all code and read-only data and the total exceeds the FLASH region size in your linker script. The overflow byte count tells you exactly how much too large the image is for the part.

What this error means

A make or link step fails with "region `FLASH' overflowed by N bytes" from arm-none-eabi-ld, after compilation succeeds.

/usr/bin/arm-none-eabi-ld: build/firmware.elf section `.text' will not fit in region `FLASH'
/usr/bin/arm-none-eabi-ld: region `FLASH' overflowed by 4096 bytes
collect2: error: ld returned 1 exit status

Common causes

The image grew beyond the part's flash

New code, large tables, or debug builds pushed the total past the FLASH size declared in the linker script.

The wrong linker script for the part

A linker script for a smaller-flash variant declares less FLASH than the actual chip provides, so a valid image appears to overflow.

How to fix it

Reduce image size or optimize for size

1. Build with size optimization (-Os) and strip unused sections.
2. Enable garbage collection of unused sections at link time.
3. Re-run the build and check the new size against FLASH.

CFLAGS += -Os -ffunction-sections -fdata-sections
LDFLAGS += -Wl,--gc-sections

Use the correct linker script FLASH size

Confirm the linker script matches the part and set the FLASH region to the chip's real size.

MEMORY
{
  FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 512K
  RAM   (xrw): ORIGIN = 0x20000000, LENGTH = 128K
}

How to prevent it

• Build release firmware with -Os and --gc-sections.
• Track image size in CI to catch growth early.
• Keep the linker script's FLASH size aligned with the part.

Frequently asked questions

Related guides

References

• GitHub Actions documentation