Preview build — page text is a draft awaiting human review. Code badges come from real compiles. The flasher is real but not yet hardware-tested; the Playground is still a preview.
Get Started
Flash size · esptool

Fix “File … will not fit in 2097152 bytes of flash” (esptool)

The image is bigger than the flash size esptool was told about. Pick the right Flash Size and partition scheme, or flash a merged binary at 0x0.

ESP32ESP32-C3ESP32-S3ESP8266ESP-01Updated 3 Nov 2026

Community draft — report a mistake

What you see

OutputOutput
esptool.py v4.8.1
Serial port COM5
Connecting....
Chip is ESP32-C3 (QFN32) (revision v0.4)
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB

A fatal error occurred: File firmware.bin (length 2133504) at offset 65536 will not fit in 2097152 bytes of flash. Use --flash_size argument, or change flashing address.

esptool refuses to write past the end of the flash chip. It adds the file length to the offset and compares the total with the flash size it was given. Here the image would end beyond that limit.

Either the flash size setting is smaller than the real chip, or a file meant for address 0x0 is being written higher up. Fix the setting, or the offset, and it writes normally.

Quick fix — try in order

  1. 1

    Set Flash Size to the real chip size

    Tools → Flash Size. Most ESP32 DevKits and C3 SuperMinis are 4MB; N16R8 S3 boards are 16MB. If you run esptool by hand, add --flash_size detect (v4) or --flash-size detect (v5).

  2. 2

    Choose a partition scheme with a bigger app slot

    Tools → Partition Scheme → “Huge APP (3MB No OTA/1MB SPIFFS)” gives a 4 MB board room for large sketches like Wi-Fi + BLE + camera.

  3. 3

    Flash a merged binary at 0x0, not 0x10000

    A “merged” or “factory” .bin already contains bootloader and partitions and must be written at 0x0. Writing it at 0x10000 makes it overflow the end of the flash.

  4. 4

    ESP-01: select the 1 MB layout

    Old ESP-01 boards have 512 KB or 1 MB flash. Pick “Generic ESP8266 Module”, Flash Size 1MB (FS: none) and keep the sketch small.

Why it happens

Why 2097152 bytes when my board has 4 MB?

esptool uses the size you pass (or the IDE passes) with --flash_size, not the detected size. A board definition or a script set to 2MB caps every write at 2 MB.

The sketch compiled fine

The compiler checks against the app partition, not the flash size given to esptool. A custom upload command or a downloaded .bin can still be too big for the address you chose.

Newer wording

esptool v5 ends the message with “Change the flash_size argument or flashing address.” Same meaning.

Board-specific notes

ESP32-C3 SuperMini: These have 4 MB flash. Some sellers' custom board files default to 2MB; select ESP32C3 Dev Module with Flash Size 4MB.

↑↓ to move · Enter to open