Introduction

This page will list some of the most common PlatformIO errors that I have encountered while using PlatformIO IDE. PlatformIO is an extension in Visual Studio Code that will allow you to program your microcontroller board.

Please specify upload_port for environment or use global --upload-port option

I encountered the below error while uploading programs from Visual Studio Code to one of my microcontroller boards.

Problem:

Looking for upload port...
Error: Please specify `upload_port` for environment or use global `--upload-port` option.
For some development platforms it can be a USB flash drive (i.e. /media/<user>/<device name>)
*** [upload] Explicit exit, status 1
=============================================== [FAILED] Took 2.03 seconds ===============================================The terminal process "C:\Users\DONSKY\.platformio\penv\Scripts\platformio.exe 'run', '--target', 'upload', '--target', 'monitor', '--environment', 'esp32dev'" terminated with exit code: 1.

Solution:

I used a different USB Type A cable when uploading my program. It turns out that this cable is only a ‘Charge Only’ cable. Some USB cable data pins are not connected but only the power pins. You would see that your microcontroller board would power up however you would encounter the error above. Make sure that you are using a USB cable that does support data exchange.

PermissionError: [WinError 5] Access is denied

I encountered PermissionError while trying to upload or build a project

Problem

> Executing task: C:\Users\DONSKY\.platformio\penv\Scripts\platformio.exe run --target cleanall --environment esp32dev <

Processing esp32dev (platform: espressif32; board: esp32dev; framework: arduino)
----------------------------------------------------------------------------------------------------------------------------------------------Removed .pio\build\esp32dev\.sconsign39.dblite
Removed .pio\build\esp32dev\partitions.bin
Removed .pio\build\esp32dev\src\main.cpp.o
PermissionError: [WinError 5] Access is denied: 'D:\\git\\platformio-projects\\esp32-projects\\esp32-send-ldr-data-websockets\\.pio\\libdeps\\esp32dev\\ESP Async WebServer\\.git\\objects\\04\\8cd02469ae0907bde6f6e847c17899131c9593':
  File "C:\users\donsky\.platformio\penv\lib\site-packages\platformio\builder\main.py", line 155:
    env.PioClean(is_clean_all)
  File "C:\Users\DONSKY\.platformio\packages\tool-scons\scons-local-4.3.0\SCons\Util.py", line 742:
    return self.method(*nargs, **kwargs)
  File "C:\users\donsky\.platformio\penv\lib\site-packages\platformio\builder\tools\piotarget.py", line 64:
    _clean_dir(libdeps_dir)
  File "C:\users\donsky\.platformio\penv\lib\site-packages\platformio\builder\tools\piotarget.py", line 49:
    os.remove(dst)

Solution

It turns out that for some unknown reason, my library dependencies got corrupted. The quick fix is to delete the .pio file in your project. This should enforce a manual rebuild of your dependencies again.

Project Tasks are all grayed out or disabled

Problem

All my project tasks (e.g. Build, Upload, Monitor, etc.) are all disabled or grayed out.

Solution

As per this thread in the PlatformIO, we need to update our PlatformIO Extension. After updating, it is now enabled. Yay!

If you don’t know how to manually update your PlatformIO extension then please look here.

[upload] UnboundLocalError : local variable ‘port’ referenced before assignment

Problem

While uploading my sketch to my microcontroller, I encountered the following issue.

[upload] UnboundLocalError : local variable 'port' referenced before assignment

Solution

My USB cable is not connected correctly to my laptop or workstation. I tried to re-insert and the error was fixed.

A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header

Problem

I encountered the following issue while uploading my sketch to my ESP8266/ESP32 Microcontroller.

Looking for upload port...
Auto-detected: COM3
Uploading .pio\build\esp32dev\firmware.bin
esptool.py v3.1
Serial port COM3
Connecting........_____....._____....._____....._____....._____....._____....._____

A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header
*** [upload] Error 2

Solution

Click the Boot button in your ESP8266/ESP32 Microcontroller.

Brownout detector was triggered

Problem

The below errors are displayed in my Serial Monitor while trying to run my program in my ESP8266/ESP32 Microcontroller board.

Brownout detector was triggered

ets Jun  8 2016 00:22:57

rst:0xc (SW_CPU_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:2
load:0x3fff0018,len:4
load:0x3fff001c,len:1044
load:0x40078000,len:10124
load:0x40080400,len:5828
entry 0x400806a8

Solution

Several factors can cause this issue.

• A bug in your program causes a memory buffer overflow so to solve it try to comment out each line of your program and upload the sketch.
• Try to switch the USB to a different USB port and reinsert it properly and then re-upload your sketch again.
• Power your Microcontroller with a separate power supply. Maybe the current supplied by the USB is not enough for all components in your circuit.
• If your project is using Wifi functionality then it could be that your microcontroller cannot connect to your Wifi. Try to wait for some time or try reconnecting the USB cable and check the Serial monitor again.

fatal error: SPI.h: No such file or directory

Problem

While building the project you encounter this error.

Solution

Add the following line in your platform.ini configuration file.

lib_deps=
    SPI

fatal error: ESP8266WiFi.h: No such file or directory

Problem

While building the project you encounter this error.

Solution

Add the following line in your platform.ini configuration file.

lib_deps=
    Wifi

A fatal error occurred: Failed to connect to ESP32: Wrong boot mode detected (0x13)! The chip needs to be in download mode.

Problem

When trying to upload the program to the ESP32 board then the following error occurred.

Solution

Click the boot button momentarily while uploading the program. You might need to do this several times until you succeed.

WARNING: Failed to communicate with the flash chip, read/write operations will fail. Try checking the chip connections or removing any other hardware connected to IOs.

Problem

I encountered this issue when trying to upload a sketch on my device and it turns out that my other connections might have been causing the issue.

Solution

Remove the wiring to other components when uploading sketches.

If this does not fix your issue then your device could be toasted or broken and needs to be replaced.

Could not open port ‘COM5’: could not >> open port ‘COM5’: PermissionError(13, ‘Access is denied.’, None, 5)

Problem

I am encountering the error above while trying to upload the sketch into my ESP32 device.

Solution

I have PyMakr extension enabled also and it causes conflict with PlatformIO. I disabled the PyMakr extension and the error was resolved.

fatal error: SoftwareSerial.h: No such file or directory

Problem

The error above is shown while trying to compile a program that uses the SoftwareSerial in ESP32.

#include <SoftwareSerial.h>

Solution

Take note that ESP32 has 3 hardware UART or Serial Communication pins so use the hardware serial in your Arduino code.

#include <HardwareSerial.h>

HardwareSerial SerialPort(2); // use UART2
void setup()  
{
  SerialPort.begin(15200, SERIAL_8N1, 16, 17); 
}

Guru Meditation Error: Core 1 panic’ed

Problem

The following errors were shown on your Serial Monitor while your program is running.

Guru Meditation Error: Core 1 panic'ed (LoadProhibited). Exception was unhandled.
Core 1 register dump:
PC : 0x400014e8 PS : 0x00060830 A0 : 0x800d133c A1 : 0x3ffb96d0
A2 : 0xa341aa26 A3 : 0xa341aa24 A4 : 0x000000ff A5 : 0x0000ff00
A6 : 0x00ff0000 A7 : 0xff000000 A8 : 0x00000000 A9 : 0x00000001
A10 : 0x00000001 A11 : 0x00060823 A12 : 0x00060820 A13 : 0x00000020
A14 : 0x00000000 A15 : 0x00000000 SAR : 0x0000000a EXCCAUSE: 0x0000001c
EXCVADDR: 0xa341aa24 LBEG : 0x4000c2e0 LEND : 0x4000c2f6 LCOUNT : 0xffffffff

ELF file SHA256: 0000000000000000

Backtrace: 0x400014e8:0x3ffb96d0 0x400d1339:0x3ffb96e0 0x400d136d:0x3ffb9700 0x400d0509:0x3ffb9720 0x40089792:0x3ffb9750

Solution

This error is a common runtime exception that gets raised by your ESP32/ESP8266 microcontrollers and the causes are different per circuit. It could be a problem in your logic or it could be an issue in your circuit. The first thing you need to do is to decode the error above so that you know what part of your program is causing this. Please see the below posts on how to decode this.

Related Content:
Debugging Arduino Errors with the ESP8266 Exception Decoder
Debugging Arduino Errors with the ESP32 Exception Decoder

Once you know the cause of the issue after decoding it then you can figure out the next course of action.

fatal error: Adafruit_GFX.h: No such file or directory

fatal error: Adafruit_I2CDevice.h: No such file or directory

Problem

I encounter the above errors while trying to drive my SSD1306 OLED display using my ESP32 microcontroller.

Solution

Quite weird to encounter this problem but upon digging further from the internet, it looks like some library dependency issues going on in PlatformIO. This thread on the PlatformIO community forum led me to a quick solution.

In your platform.ini file, add the following option lib_ldf_mode=deep. Do a Full Clean task and then Build your project again and voila! The error is resolved!

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
lib_ldf_mode=deep
lib_deps = 
	bblanchon/ArduinoJson@^6.21.3
	adafruit/Adafruit SSD1306@^2.5.7
	ricmoo/QRCode@^0.0.1
	links2004/WebSockets@^2.4.1

fatal error: SoftwareSerial.h: No such file or directory

Problem

The following error pops up when trying to use SoftwareSerial in your Arduino projects.

Solution

Please see the following post about Using ESP32 SoftwareSerial in your Arduino Projects

Wrap up

I will keep updating this page with the list of common PlatformIO errors that I have encountered so that it will help you somehow whenever you encounter any errors.

Happy Exploring!

Related Posts:

Looking for more projects then head on to my YouTube channel.