Troubleshooting

Flashing problems can be fiddly to troubleshoot. Try the suggestions here if you’re having problems:

Bootloader Won’t Respond

If you see errors like “Failed to connect” then your chip is probably not entering the bootloader properly:

  • Check you are passing the correct serial port on the command line.

  • Check you have permissions to access the serial port, and other software (such as modem-manager on Linux) is not trying to interact with it. A common pitfall is leaving a serial terminal accessing this port open in another window and forgetting about it.

  • Check the chip is receiving 3.3V from a stable power source (see Insufficient Power for more details.)

  • Check that all pins are connected as described in Entering the Bootloader. Check the voltages at each pin with a multimeter, “high” pins should be close to 3.3V and “low” pins should be close to 0V.

  • If you have connected other devices to GPIO pins, try removing them and see if esptool starts working.

  • Try using a slower baud rate (-b 9600 is a very slow value that you can use to verify it’s not a baud rate problem).

Writing to Flash Fails Part Way Through

If flashing fails with random errors part way through, retry with a lower baud rate.

Power stability problems may also cause this (see Insufficient Power.)

Writing to Flash Succeeds but Program Doesn’t Run

If esptool can flash your module with write_flash but your program doesn’t run, check the following:

Wrong Flash Mode

Some devices only support the dio flash mode. Writing to flash with qio mode will succeed but the chip can’t read the flash back to run - so nothing happens on boot. Try passing the -fm dio option to write_flash.

See the SPI Flash Modes page for a full description of the flash modes and how to determine which ones are supported on your device.

Insufficient Power

The 3.3V power supply for the ESP chip has to supply large amounts of current (up to 70mA continuous, 200-300mA peak, might be slightly higher). You also need sufficient capacitance on the power circuit to meet large spikes of power demand.

Insufficient Capacitance

If you’re using a pre-made development board or module then the built-in power regulator & capacitors are usually good enough, provided the input power supply is adequate.

Note

This is not true for some very simple pin breakout modules - similar to this. These breakouts do not integrate enough capacitance to work reliably without additional components. Surface mount OEM modules like ESP-WROOM02 and ESP-WROOM32 require an external bulk capacitor on the PCB to be reliable, consult the module datasheet.

Power Supply Rating

It is possible to have a power supply that supplies enough current for the serial bootloader stage with esptool, but not enough for normal firmware operation. You may see the 3.3V VCC voltage droop down if you measure it with a multimeter, but you can have problems even if this isn’t happening.

Try swapping in a 3.3V supply with a higher current rating, add capacitors to the power line, and/or shorten any 3.3V power wires.

The 3.3V output from FTDI FT232R chips/adapters or Arduino boards do not supply sufficient current to power an ESP chip (it may seem to work sometimes, but it won’t work reliably). Other USB TTL/serial adapters may also be marginal.

Missing Bootloader

ESP-IDF and uses a small firmware bootloader program. The hardware bootloader in ROM loads this firmware bootloader from flash, and then it runs the program. On ESP32, the bootloader image should be flashed by ESP-IDF at offset 0x1000.

Refer to ESP-IDF documentation for details regarding which binaries need to be flashed at which offsets.

SPI Pins Which Must Be Disconnected

Compared to the ROM bootloader that esptool talks to, a running firmware uses more of the chip’s pins to access the SPI flash.

If you set “Quad I/O” mode (-fm qio, the esptool default) then GPIOs 7, 8, 9 & 10 are used for reading the SPI flash and must be otherwise disconnected.

If you set “Dual I/O” mode (-fm dio) then GPIOs 7 & 8 are used for reading the SPI flash and must be otherwise disconnected.

Try disconnecting anything from those pins (and/or swap to Dual I/O mode if you were previously using Quad I/O mode but want to attach things to GPIOs 9 & 10). Note that if GPIOs 9 & 10 are also connected to input pins on the SPI flash chip, they may still be unsuitable for use as general purpose I/O.

In addition to these pins, GPIOs 6 & 11 are also used to access the SPI flash (in all modes). However flashing will usually fail completely if these pins are connected incorrectly.

Early Stage Crash

Use any of Serial terminal programs to view the boot log. (ESP32 baud rate is 115200bps). See if the program is crashing during early startup or outputting an error message.

Serial Terminal Programs

There are many serial terminal programs suitable for debugging & serial interaction. The pyserial module (which is required for esptool) includes one such command line terminal program - miniterm.py. For more details see this page or run miniterm -h.

Tracing Esptool Interactions

Running esptool.py --trace will dump all serial interactions to the standard output (this is a lot of output). This can be helpful when debugging issues with the serial connection, or when providing information for bug reports.

See the related Advanced Topics page for more information.