Something not working?

Manual boot

Failed to connect to ESP32: No serial data received.

The chip has to be in download mode to take an upload. It reads GPIO 0 once, at the end of every restart: low means download mode, high runs your program. Manual boot is making GPIO 0 low at that moment.

1. Hold BOOT.
2. Tap RESET (some boards call it EN), still holding BOOT.
3. Release BOOT.
4. Click Upload.

No RESET button? Hold BOOT, plug in the USB cable, then let go: powering on is a restart too. If manual boot works every time and automatic never does, the auto-reset circuit is not getting its signals, usually the cable.

• A fatal error occurred, Failed to connect to ESP32Install the toolchain
• The board only uploads if I hold BOOTThe EN and BOOT buttons
• It uploads and then stays in download modeThe EN and BOOT buttons
• The port disappears the moment the sketch runsWhen uploads fail
• The port disappears whenever the sketch crashesSerial ports and drivers

The computer cannot find the board

No port in the Port menu, or two, or a different number each time.

Nine times in ten it is the cable: plenty of cables carry power and no data, and a board that lights up is not a board that is talking. Try another cable first, then the driver for your board's USB chip. On macOS use the cu port, not the tty one.

• The board does not appear in the Port menuInstall the toolchain
• Two ports appear and only one worksSerial ports and drivers
• The port number changes between sessionsSerial ports and drivers
• Permission denied on LinuxWhen uploads fail

The upload worked, but I see nothing

An empty Serial Monitor, or boxes and question marks.

The Serial Monitor's baud rate has to match Serial.begin: set both to 115200. Boxes and question marks mean the two rates disagree. Silence usually means the wrong port, or a sketch that printed its greeting before you opened the monitor: press EN and watch again.

• The monitor prints nothing at allHello world over serial
• The monitor prints boxes and question marksHello world over serial
• There is a wall of garbage before my first lineHello world over serial
• The port exists but nothing is ever printedSerial ports and drivers
• It uploads and then prints nothingInstall the toolchain

The board keeps resetting

It reboots when Wi-Fi starts, when a motor moves, or every few minutes.

Read the first line of the serial log. A brownout message is a power message, not a code one. The usual cause is the Wi-Fi transmit burst on a thin cable or a weak supply: use a shorter data cable and a better supply, and put 100 µF across 3.3 V close to the board. A servo or a relay never goes on the board's 3V3 pin.

• The board resets the moment Wi-Fi connectsPower and the 3V3 rail
• A servo makes the board reboot every time it movesPower and the 3V3 rail
• The board resets when Wi-Fi transmitsBattery and power budget
• It reboots only when Wi-Fi is transmittingCrash dumps and the watchdog
• The watchdog fires and my code is not stuckCrash dumps and the watchdog
• It connects, then drops every few minutesWi-Fi station mode
• Uploads work but the board resets over and over afterwardsWhen uploads fail

My board will not connect to Wi-Fi

Dots forever, or it works at your desk and not at the customer's.

No ESP32 has a 5 GHz radio, so a 5 GHz-only network never appears. If the password is right and it still refuses, print the disconnect reason code instead of guessing: 15 is a bad password, 201 means the network was never found.

• It joins on your desk and not at the customer's houseWi-Fi station mode
• The password is right and it still refusesWi-Fi station mode
• It prints dots forever and never joinsSeveral networks, one board
• The user typed the password correctly and it still failedWi-Fi provisioning

A pin does nothing, or the board will not boot

It boot-loops with a module attached, or an input never changes.

Some pins are not free: the flash pins, the input-only pins with no pull-up, and the strapping pins that are read at reset. Which numbers they are depends on the chip, and the pin article lists them per chip. On the original ESP32 the second ADC block does not work while Wi-Fi is on.

• The board boot-loops as soon as I attach a moduleThe pins you cannot use
• The board only boots with the sensor unpluggedThe pins you cannot use
• A button on GPIO 34 never reads as pressedThe pins you cannot use
• analogRead worked until I added Wi-FiThe pins you cannot use

The sketch is too big

Sketch too big, or OTA fails with not enough space.

The app partition is what your code has to fit in, not the flash size: on a 4 MB board half goes to the second OTA slot and a chunk to the filesystem. Set Flash Size to what the board really has, and choose the partition scheme at the start of a project.

• Sketch too big, and the board has 4 MBPartition tables and flash size
• The IDE says my board has 4 MB and esptool says 16Partition tables and flash size
• OTA fails with not enough spacePartition tables and flash size
• Sketch too big, as soon as OTA is enabledOTA updates