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!

51 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!

    Reply
  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?

    Reply
  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?

    Reply
    • 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

      Reply
  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

    Reply
    • 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 🙂

      Reply
  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

    Reply
    • 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 🙂

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

    Reply
  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

    Reply
    • 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

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

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

    Reply
    • 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!

      Reply
  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?

    Reply
    • 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

      Reply
  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).

    Reply
  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?

    Reply
  13. Hi Sara,

    For me, the problem is that after disconnecting my ESP32 with a LoRa chip, the uploaded can be finished. Then I connect them with UART RX and UART TX. But no text or results show in the Serial Monitor even I use some commond like AT.
    I am sure the connection program is well. So could you please give some advice?

    Thank you

    Reply
  14. Hi, Thanks for very amazing tutorial

    could you help me find a solution for this problem

    ets Jun 8 2016 00:22:57

    rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
    configsip: 0, SPIWP:0xee
    clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
    mode:DIO, clock div:1
    load:0x3fff0018,len:4
    load:0x3fff001c,len:1100
    load:0x40078000,len:10088
    load:0x40080400,len:6380
    entry 0x400806a4
    ets Jun 8 2016 00:22:57

    rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
    configsip: 0, SPIWP:0xee
    clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
    mode:DIO, clock div:1
    load:0x3fff0018,len:4
    load:0x3fff001c,len:1100
    load:0x40078000,len:10088
    load:0x40080400,len:6380
    entry 0x400806a4
    ets Jun 8 2016 00:22:57

    rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
    configsip: 0, SPIWP:0xee
    clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
    mode:DIO, clock div:1
    load:0x3fff0018,len:4
    load:0x3fff001c,len:1100
    load:0x40078000,len:10088
    load:0x40080400,len:6380
    entry 0x400806a4
    ets Jun 8 2016 00:22:57

    rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
    configsip: 0, SPIWP:0xee
    clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
    mode:DIO, clock div:1
    load:0x3fff0018,len:4
    load:0x3fff001c,len:1100
    load:0x40078000,len:10088
    load:0x40080400,len:6380
    entry 0x400806a4

    Reply
    • Hi Dany.
      Your ESP32 is rebooting continuously. This means that you probably have something wrong in your code that crashes the ESP32.
      Regards,
      Sara

      Reply
    • Hi Danny, I have had this problem before. I found on another forum a solution by adding a capacitor on a specific pin. I cannot remember what type of ESP32 it was… , this device was a clone and had other problems. I thrown it out… Do not look in your software, I had lost hours and hours with this pseudo Lilygo TTGO appliance before buying a genuine product. Regards, Pierre.

      Reply
  15. Hi.
    I uploaded my first code to my esp32 devkit v1 board and I worked perfectly and trying to upload the second code, I keep getting this error message

    *A fatal error occurred: Timed out waiting for packet content*

    And when I open the serial monitor, this message keeps coming up

    rst: 0x10 (RTCWDT_RTC_RESET), boot:0x33 (SPI_FAST_FLASH_BOOT)
    flash read err, 1000
    ets_main.c 371
    ets Jun 8 2016 00:22:57

    Reply
  16. Hi I am having trouble programming an ESP32 using arduino 1.8.9 I get a virus alert and the message Arduino15\\packages\\esp32\\hardware\\esp32\\1.0.4/tools/gen_esp32part.exe I suspect my virus detector has eliminated this “package” It was installed using the https://dl.espressif.com/dl/package_esp32_index.json,http://arduino.esp8266.com/stable/package_esp8266com_index.json,https://dl.espressif.com/dl/package_esp32_index.jsonin preferrences.

    An suggestions would be appreciated as I have spent a lot of time trying to resolve this issue. I am also having problems installing arduino !.8.12. it seems to require all the libraries of the existing 1.8.9 and does not automatically install them. Again any help will be appreciated

    Reply
  17. Hi Sara,
    I submit to you a problem with a secure router link to the ESP32 shield

    the Esp32 does not worked on a secure router (name broadcastOn)
    IT WORK fine on an open router (factory set )

    the declaration are in according with Arduino web site concerning both routers

    // begin with secure router
    status = WiFi.begin(ssid,password);

    // begin with unsecure router
    status = WiFi.begin(ssid);

    HERE are the output of two consoles

    =====abort with the secured router=====
    Console outpup
    16:03:50.630 -> Connecting to broadcastOn
    16:03:50.715 -> …………………… and so on permanently!
    CAUSE infinte loop on (WiFi.status() != WL_CONNECTED)

    =========work fine with an “open” router (factory set)======
    Console outpup
    16:08:40.215 -> Connecting to linksys
    16:08:40.362 -> ..
    16:08:44.369 -> WiFi connected.
    16:08:44.369 -> IP address:
    16:08:44.369 -> 192.168.1.101

    only one loop at the test (WiFi.status() != WL_CONNECTED)
    ————–
    HERE is the setup
    =====Software======
    Arduino IDE version 1.8.12
    WiFi.h, version 2.1
    WiFi.cpp, version 2.1
    the wifi librairy is

    C:\Users\usager\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.4\libraries\WiFi
    (dated on 2016)

    ======Hardware
    model cart: DOITESP32 DEVKIT V1
    ESPDUINO-32 chip esp32-wroon-32
    Chip is ESP32D0WDQ5 (revision 1)

    setup of the secured router
    SSID: broadcastOn
    securty: WPA2 Personal with AES chiffrement

    setup of the NO secured router
    SSID: linksys
    securty: “nothing”

    You ask… Do I have check the right password variable. Yes I made double check ( Hi)

    Have you a solution?
    thk for help

    Reply
      • Hi Sara,
        first, thk for fast reply. I appreciate.
        second, I will follow your suggestion conceerning Enterprise security link.
        I can you back new if you want.
        third, I am supprised that anybody give an answer on a web blog or community help about my issue. Anyway..
        fourth, thk for the ESP32 librairy. Can I share it with my students or they need to creater their own account. For your information, the college where I work agree to respect the “droits d’auteurs”.

        I hope wy english writing is not too bad 🙂
        Alain

        Reply
        • Hi again.
          If you find something, please share, it can be helpful for others.

          Anyone can consult/use our tutorials on the RNT blog. When using our projects, please make a reference to our blog.

          When it comes to our premium courses (accessed through the RNTLAB.com website), they need to create their own account. If you need further help about access to courses, you can submit a question here: https://randomnerdtutorials.com/support/
          Regards,
          Sara

          Reply
  18. Howdy,

    A small suggestion to complete this guide: you could mention the malfunction that occurs when using WiFi and reading the ADC2 analog pins simultaneously .

    A small table of contents in the preamble would also help orient the reader to the problem he may encounter.

    Thank you again for the valuable information in this guide.

    Best wishes,
    Steph

    Reply
  19. I have been struggling with: “SPIFFS Upload failed!” when using “ESP32 Sketch Data Upload”.

    It turns out that I still had the “Serial Monitor” open from a previous experiment; closing the “Serial Monitor” solved the problem

    Reply
    • Great!
      Thanks for sharing that. You need to close the Serial Monitor so that it can establish a proper serial connection with your ESP32.
      Regards,
      Sara

      Reply
  20. I have implemented several ESP32 and ESP8266 projects with the Arduino IDE that work fine…once the IP address shows up on the list of ports (Tools | Port: | Serial Ports). The problem is, it will often take hours or days for the IP address to show up. In the meantime I can upload new sketches via the COM port, but cannot access the WiFi web page until the IP address shows up on the list.

    In most cases I KNOW what the IP address is, as the Serial Monitor will show the IP address that has been assigned. I enter the IP address into the Chrome Address bar, wait a few seconds, and get a “This site can’t be reached” error.

    The IP address is shown on my router’s admin page and is identified as “expressif”, so the router “sees” the ESP.

    Any ideas what I need to do to stimulate a response – from the router, ESP, IDE or…???

    Reply
  21. Greetings,

    Thank you for this post. I have a problem I hope you can help with. I have my code running fine with information being displayed on the serial monitor and posting data on a node-Red UI page. All good.

    If I press the ESP32 rest button, the serial monitor dumps some jiberish and then stops. It does not go “grey” as it does when I am compiling and reloading, it stays “white” but nothing prints. As well, the node-Red dashboard is no longer being updated. I have tried closing and re-opening the serial monitor with no luck and have varified the com port and buad rates are correct.

    I have to reload the code to get things running again.

    Am I missing a sequence when hitting the reset button? I would expect the program to just restart but that does not seem to be happening.

    Reply
    • Hello Tim, to be honest I’m not sure what’s going on based on just that information (I would need to personally test your project to see what’s missing). A code that is flashed in your ESP it will always run after a restart (press the RESET button)…

      Note: you can ignore that jiberish

      Reply
  22. Hi everyone. After starting in 8266 i wanna try the ESP32. Problem is that i cant compile anything due to this error.

    exec: “{runtime.tools.esptool_py.path}/esptool.exe”: file does not exist
    Error compiling for board ESP32 Dev Module.

    I tried some “solutions” that i found over the internet, but no luck yet.
    Does anyone experienced this? With ESP8266 everything is ok.

    Reply

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.