ESP32 Troubleshooting Guide | Random Nerd Tutorials

The ESP32 has a few common problems, specially when you are trying to upload new sketches or install the ESP32 add-on on the Arduino IDE. This guide is dedicated to the ESP32 when programmed with Arduino IDE. Here, we provide a compilation with some of the most common problems with the ESP32 and how to fix them.

Important: make sure you have the latest Arduino IDE installed. Using a different Arduino IDE version might cause other unexpected problems and errors.

Note: Espressif found some silicon design errors in the ESP32 which might be responsible for some unexplained errors/behavior. The errors are detailed in the following document:

• https://espressif.com/sites/default/files/documentation/eco_and_workarounds_for_bugs_in_esp32_en.pdf 

Of particular note are 3.1 (relating to power up and deep sleep wake-up) and 3.4 (relating to not restarting on brownout). The old v0 and v1 chips were used in modules labelled ESP32-WROOM-32. The errors are fixed in modules ESP32-WROOM-32E and any other ESP32 designations ending in E (see espressif for more info). So, to avoid getting issues with your ESP32, we recommend searching for the ones labeled ESP32-WROOM-32E.

1. How do I install the ESP32 add-on for the Arduino IDE?

There’s an add-on for the Arduino IDE that allows you to program the ESP32 using the Arduino IDE and its programming language. Follow one of the next Units to prepare your Arduino IDE to work with the ESP32 in your operating system:

• Windows instructions – ESP32 Board in Arduino IDE 2 (or check the legacy Arduino IDE)
• Mac and Linux instructions – ESP32 Board in Arduino IDE 2 (or check the legacy Arduino IDE)

2. I can’t see the ESP32 boards in the Arduino IDE Tools menu (Windows PC)

If you still don’t see the boards in the Arduino IDE, make sure you click on the small arrow (highlighted in the figure below) to scroll all the way down through the boards:

If at this moment you can’t find your ESP32 board name, we recommend repeating the installation process from scratch.

• Windows instructions – ESP32 Board in Arduino IDE 2 (or check the legacy Arduino IDE)
• Mac and Linux instructions – ESP32 Board in Arduino IDE 2 (or check the legacy Arduino IDE)

3. C:\\Users\\ User\\Documents \\Arduino\\ hardware\\ espressif\\ esp32/tools /xtensa-esp32-elf /bin/ xtensa-esp32- elf-g++”: file does not exist

After installing the ESP32 add-on, if you open the Arduino IDE and it fails to compile code to your ESP32 board, we recommend re-running the Arduino IDE ESP32 add-on installation.

Note: Windows PCs often have multiple Arduino IDE versions installed (portable and local installations). Make sure you are running the Arduino IDE where you installed the ESP32 add-on.

4. A fatal error occurred: “Failed to connect to ESP32: Timed out… Connecting…”

When you try to upload a new sketch to your ESP32 and it fails to connect to your board, it means that your ESP32 is not in flashing/uploading mode.

Having the right board name and COM por selected, follow these steps:

• Hold-down the “BOOT” button in your ESP32 board

• Press the “Upload” button in the Arduino IDE to upload a new sketch:

• After you see the “Connecting….” message in your Arduino IDE, release the finger from the “BOOT” button:

• After that, you should see the “Done uploading” message

That’s it. Your ESP32 should have the new sketch running. With those boards/with that setup, after uploading a new sketch, press the “ENABLE” button to restart the ESP32 and run the new uploaded sketch.

You’ll also have to repeat that button sequence every time you want to upload a new sketch. But if you want to solve this issue once for all without the need to press the BOOT button, follow the suggestions in the next guide:

• [SOLVED] Failed to connect to ESP32: Timed out waiting for packet header

To be honest we’re not sure why that happens with the newer boards. We don’t have any ESP32 board with that behavior. We think there might be something different with your specific board or the Arduino IDE fails to send the right command sequence to put the ESP32 automatically in flashing/uploading mode.

5. Error compiling WiFiScan sketch

If you try to upload the ESP32 WiFiScan.ino sketch provided in the ESP32 Getting Started guide:

And it fails to compile with a similar error message:

In function ‘void setup()’: ScanNetworks:52: error: ‘class WiFiClass’ has no member named ‘firmwareVersion’ String fv = WiFi.firmwareVersion();

It looks like your Arduino IDE is compiling the WiFi library for the Arduino board (instead of using the ESP32 WiFi library).

Note: you’ll probably never use any WiFi shield with your Arduino board, right? If you don’t use it, you need to remove that folder/those folders from your Arduino IDE (move it to your desktop, for example).

The WiFi library is located, in a similar path:

C:\Users\ruisantos\Downloads\arduino-1.8.7-windows\arduino-1.8.7\libraries\WiFi

And/or at:

C:\Users\ruisantos\Documents\Arduino\libraries\libraries\WiFi

After removing the entire WiFi library folder from one location or both locations, restart your Arduino IDE and try to compile the code again.

6. COM Port not found/not available

If you plug your ESP32 board to your computer, but you can’t find the ESP32 Port available in your Arduino IDE (it’s grayed out):

It might be one of these two problems: 1. USB drivers missing or 2. USB cable without data wires.

1. If you don’t see your ESP’s COM port available, this often means you don’t have the USB drivers installed. Take a closer look at the chip next to the voltage regulator on board and check its name.

The ESP32 DEVKIT V1 DOIT board uses the CP2102 chip.

Go to Google and search for your particular chip to find the drivers and install them in your operating system.

You can download the CP2102 drivers on the Silicon Labs website.

After they are installed, restart the Arduino IDE and you should see the COM port in the Tools menu.

2. If you have the drivers installed, but you can’t see your device, double-check that you’re using a USB cable with data wires.

USB cables from power banks often don’t have data wires (they are charge only). So, your computer will never establish a serial communication with your ESP32. Using a proper USB cable should solve your problem.

If you need further details on how to install these drivers, you can follow these guides:

• Install USB Drivers – CP210x USB to UART Bridge (Windows PC)
• Install USB Drivers – CP210x USB to UART Bridge (Mac OS X)

7. Arduino IDE Serial Monitor “doesn’t work”

If the ESP32 is only printing weird text or gibberish messages in your Arduino IDE Serial Monitor, make sure you have the right COM port selected and set the right baud rate as shown below. In most examples, we’re using 115200 baud rate.

8. Error: “Brownout detector was triggered”

When you open your Arduino IDE Serial monitor and the error message “Brownout detector was triggered” is constantly being printed over and over again. It means that there’s some sort of hardware problem.

It’s often related to one of the following issues:

• Poor quality USB cable;
• USB cable is too long;
• Board with some defect (bad solder joints);
• Bad computer USB port;
• Or not enough power provided by the computer USB port.

Solution: try a different shorter USB cable (with data wires), try a different computer USB port or use a USB hub with an external power supply.

9. I can’t make the ESP32 add-on work with Arduino IDE

If you’ve followed all the troubleshooting tips and the ESP32 add-on doesn’t work with the Arduino IDE, we recommend experimenting programming the ESP32 with VS Code and PlatformIO IDE. Read the following guide:

• Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266 (Windows, Mac OS X, Linux Ubuntu)

Wrapping Up

We hope you’ve found this guide useful. If you encounter any other issues, please post them in comments below and we’ll try to help you solve your problem.

We have other tutorials with ESP32 that you might like:

• ESP32 with Multiple DS18B20 Temperature Sensors
• ESP32 Data Logging Temperature to MicroSD Card
• ESP32 with DC Motor and L298N Motor Driver – Control Speed and Direction

We hope you’ve found this tutorial useful. If you like ESP32 and you want to learn more, we recommend enrolling in Learn ESP32 with Arduino IDE course.

Thanks for reading.