ESP32 Troubleshooting Guide

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.

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:

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.

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 intallation.

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:

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 powerbanks often don’t have data wires (they are charge only). So, your computer will never establish a serial communication with your ESP32. Using a a proper USB cable should solve your problem.

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 Atom text editor and PlatformIO IDE. Follow this post: Atom text editor with PlatformIO IDE to program the ESP32.

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:

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.


Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »

Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »


Enjoyed this project? Stay updated by subscribing our weekly newsletter!

30 thoughts on “ESP32 Troubleshooting Guide”

  1. Thanks! It took me a lot of time some weeks ago to make my ESP32 work, and this Tutorial seems to be a very good resume of all required steps. I fully recommend it to every one!
    Well done!

  2. When Verifying a sketch with the Asyncmqttclient.h include I get this error:

    C:\Users\wbunker\Documents\Random Nerd\ESP32\ESP32-Course-master\code\MQTT\ESP32_Client_1_LED_DS18B20\ESP32_Client_1_LED_DS18B20.ino:11:29: fatal error: AsyncMqttClient.h: No such file or directory

    compilation terminated.

    Which add-on lib do I need to install?

  3. Hi! Thanks for the full page of info. I ordered 5 ESP32 DevKitC’s and four of them work just fine, but the fifth one simply disagrees with me. It appears as COM8 just like all the others, but it doesn’t respond to the button dance like the others. I have tried info found on other pages, such as grounding GPIO15 at upload, but to no avail.

    Is there a way to get this connected, or, is it bricked for good?

    • Hi.
      If the ESP32 is similar to the others and you’re doing the exact same procedure, I have no idea why it is not working 😐
      Unfortunately, I don’t have any other procedure to get it working.
      Regards,
      Sara

  4. Hi there:
    Could you help me find a sulution on “A fatal error occurred: MD5 of file does not match data in flash!”
    MD5 is same in every attempt.
    Thanks
    Regards

    • Hi Tim.
      I’ve never encountered that error.
      But after searching about that, I’ve found that many users resolve that situations by disconnecting all wires connected to pins before uploading the code.
      Take a look at this thread:
      github.com/espressif/esp-idf/issues/50
      Or it can be a power issue:
      github.com/espressif/esptool/issues/220
      I hope this helps,
      Regards,
      Sara 🙂

  5. Bonjour. par 2 fois je vous ai adressé un message,concernant la lenteur de la compilation d’un esp32 par rapport a l’esp8266 .pourquoi?. si vous voulez que j’achète votre cours ,il faudrait déja répondre à mes qestions!.Salutations

    • Hi Robert.
      I don’t understand French (I used Google translator).
      Where did you send the message to?
      We receive a lot of comments everyday and sometimes it is difficult to get track and answer all of them, I’m sorry for the trouble.
      ESP32 should upload code much faster than the ESP8266.
      Sometimes you get a message with a lot of dots and it never uploads the code. You should press the BOOT button when uploading the code.
      After you see the “Connecting….” message in your Arduino IDE, release the finger from the “BOOT” button.
      I’m not sure if this is what you were asking for.
      Regards,
      Sara 🙂

  6. I have been using the ESP32 since it came out. I originally use Arduino IDE without a board support package. When the board support package became available I used it but need to hold down the boot button to start the connection. I am using the esp32 Thing from sparkfun. Never needed to do this before. It a pain when the board boot button is not readily accessible. I hope this gets fixed. I looked at the board support file and it looks like the old one for RTS and RESET.

  7. I have tried multiple ways of installing but I keep getting …/BLEServer.cpp:21:22: fatal error: gatt_api.h: No such file or directory

    gatt_api.h dose exist it is in this directory :-
    C:\Users\MyUserName\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.0\tools\sdk\include\bluedroid\stack

    Any ideas?

    Thakns

    • Hi.
      I’ve never faced that error before. I’m not sure why it happens.
      But it seems that you’re missing the gatt_api.h file.
      Do you see that file in that directory path? C:\Users\MyUserName\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.0\tools\sdk\include\bluedroid\stack

  8. Thanks for the great tutorial.

    I have 2 Heltec ESP32 LoRa modules connected (no version is shown), so one is a node with one temperature sensor and the other is a gateway connected to the TTN. The problem is that it’s only working for spreading factor 7!!!
    Any other SF that I configure, the Heltec display only shows “READY” and IP (which I am also not able to access as webserver). Weird…

    I’m using the matthijskooijman library for 915 MHz.
    If I open the serial monitor and reset the gateway, it seems that the settings I make are not having any effect.
    Even confirming that it is “#define _SPREADING SF8”, the serial monitor shows “Listening at SF7”. Are there any other parameters that I need to configure for SF? I’m also not able to access through IP, it does not load the page.

  9. I get the error ” Error downloading downloads.arduino.cc/packages/package_index.json” each time at the bopard manager menu and the ESP32 system doent come up with a search. Kindly help with your thoughts on this problem.

    • Hello, it looks like you have a wrong URL in the boards manager field. Please copy the exact URLs that I mention in that project. Make sure you are also running the latest version of the Arduino IDE.
      Thanks!

  10. COM Port not found/not available, I have two esp32 working in my table, but one dont conect to pc anymore. They both are equals, one conect with no problem but the other don’t conect anymore. I think I have burn but how?

    • Hi Igor.
      With that information it is difficult to understand what is going on with your ESP32.
      The ESP32 will “burn” if you connect its GPIOs to a voltage higher than 3.3V (I don’t know if it is the case).
      If both of your ESP32 boards are brand new, maybe one of them is faulty.
      Regards,
      Sara

  11. Sara, thanks for the great article, the bit about holding down the reset was very helpful.

    I have been developing on the ESP32 for a while (after learning about the reset button) but after the latest IDE update, it will not compile.

    The initial error was that it could not find an include file (I forget which one now). I started looking through the log and ended up copying the libraries over almost everywhere (i.e. downloaded libs from github, copied to \users\xxx\Documents\Arduino, \users\xxx\appdata\local\Ardiono15\packages, and \Program Files (x86)\Arduino\hardware).

    That fixed most of the include errors, but I still have problems. The latest:
    ——————————
    C:\Users\xxx\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.0\libraries\WiFi\src\WiFiAP.cpp:40:43: fatal error: dhcpserver/dhcpserver_options.h: No such file or directory

    Multiple libraries were found for “WiFi.h”
    compilation terminated.
    ——————————

    This all seems very wrong to me. At first, I even deleted all the libraries and re-installed. It seems to me that someone screwed up somewhere. I’m just surprised I don’t see more complaints. (I can’t be the only one).

  12. Hi Sara,
    I am having a repetitive issue with the ESP32 Dev Board and help you may be able to help. I am using the ESP8266 on 3 similar applications and now the ESP32 on 2 but lately it seems the newer boards are giving this same issue repeatedly. The board is ESP32S with chip ESPRESSIF ESP32-WROOM-32, looks the same as the one at the top of this post even with the green dot.
    I am measuring 8 thermistors through a multiplexer and then into one pin, adc0. This is done because I require the temperature difference to be accurate and so they all use the same resistor, eliminating one variable in the circuit. The results are then sent to IoT platforms via wifi.
    The issue is that it all works great for a few hours (anywhere from 8 to 24) but then the results get extremely noisy for no reason. The noise can be fixed by a software reset. But why is this happening and is there a way to get control of it?

Leave a Comment

Download our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.