Search this site

Try a part name, a rupee figure, or the fault you are chasing.

Free project pack

Flashing MicroPython onto an ESP32 fails: erase flash first and use the right offset

Erase the flash, then write the firmware at the right offset.

What the message means

Old firmware or a wrong offset gives a board that does not boot. The offset differs between chip types.

Fix it in this order

  1. Download the firmware that matches your chip type.
  2. Put the board in download mode if it does not enter it by itself.
  3. Run the erase command of esptool for the port.
  4. Write the firmware at the offset given on the download page for your chip.
  5. Press reset and open a serial terminal at 115200.
  6. Try a lower baud rate for flashing if it fails.

Why it happens

Flashing MicroPython over old firmware without erasing can leave a corrupted file system and strange start-up errors. Erase the flash first, then write the new image.

Run erase_flash with esptool, then write the firmware at the address given on the MicroPython download page for your chip, since the offset differs between the ESP32, the S3 and the C3. Put the board in boot mode if the tool cannot connect.

If you see this, do this

You seeDo this
Boot loop after flashingWrong offset or chip type.
Flash command times outDownload mode or cable.

Thonny connection, board not detected.

Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.

Why this happens

The ESP32 family stores its boot loader at a chip-specific address. The classic ESP32 and the S2 expect it at 0x1000, while the S3 and C3 expect it at 0x0. A MicroPython image is built with the loader inside it. Writing an S3 image at 0x1000 puts it where the chip does not look, so the board fails to boot, often repeating a boot message.

Erasing first removes old partitions and a file system from an earlier firmware. A mix of old and new layouts can leave a board that boots but fails on first use. Erasing takes a few seconds and costs nothing but your stored files.

How to confirm the cause

  • Run esptool chip_id to confirm the real chip type; some boards are sold with the wrong label.
  • Check the firmware file name against the chip type, and the offset against the download page.
  • Look at the serial output after reset at 115200 baud for boot loop messages.
  • If the tool cannot connect, hold BOOT while pressing EN, release EN, then release BOOT, and try again.
  • Try a lower baud rate for writing, such as 115200, to rule out a poor cable.

Worked example

Run in a terminal, replacing COM5 and firmware.bin. The offsets follow the MicroPython download page for each chip, so check it for yours.

python -m esptool --port COM5 chip_id
python -m esptool --port COM5 erase_flash
python -m esptool --port COM5 --baud 460800 write_flash -z 0x1000 firmware.bin

# ESP32 and ESP32-S2: 0x1000
# ESP32-S3 and ESP32-C3: 0x0

Common mistakes

  • Using the S3 offset for a classic ESP32 or the other way round.
  • Using a charge-only USB cable.
  • Leaving a serial terminal open on the port while flashing.
  • Choosing the wrong build variant for the board’s memory.

If this did not fix it

  • Check that the USB-serial driver (CH340 or CP210x) is installed.
  • Check the supply: a weak USB port can cause failures during writing.
  • Check the flash size setting if the board reports a different size.
  • Try Thonny’s built-in installer as a second method.