Troubleshooting

Package Manager

Fix Windows Path Length Limitation (MAX_PATH)

Windows enforces a default 260-character path limit (MAX_PATH). Deeply nested package dependencies—such as ESP-IDF or ESP32-Arduino framework easily exceed this threshold, resulting in FileNotFoundError or extraction failures during package installation.

To resolve this issue, enable Long Paths in Windows using one of the following methods:

Method 1: PowerShell (Recommended)

Run the following command in PowerShell as Administrator, then restart your system:

Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

Method 2: Registry Editor

Press Win + R, type regedit, and press Enter.
Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.
Double-click LongPathsEnabled and change its value to 1.
Restart your computer.

Hint

If you lack administrative privileges to modify system settings, you can shorten the default PlatformIO storage path instead. Set the PLATFORMIO_CORE_DIR environment variable to a shorter location (for example, C:\pio).

[Error 5] Access is denied

PlatformIO installs all packages to “core_dir/packages” directory. You MUST HAVE write access to this folder. Please note that PlatformIO does not require “sudo”/administrative privileges.

Solution 1: Remove folder 

A quick solution is to remove “core_dir/packages” folder and repeat installation/building/uploading again.

Solution 2: Antivirus 

Some antivirus tools forbid programs to create files in the background. PlatformIO Package Manager does all work in the background: downloads package, unpacks archive in temporary folder and moves final files to “core_dir/packages” folder.

Antivirus tool can block PlatformIO, that is why you see “[Error 5] Access is denied”. Try to disable it for a while or add core_dir directory to exclusion/whitelist.

Solution 3: Run from Terminal 

As we mentioned in “Solution 2”, antivirus tools can block background file system operations. Another solution is to run PlatformIO Core (CLI) from a system terminal.

Open System Terminal, on Windows cmd.exe (not PlatformIO IDE Terminal)

Build a project and upload firmware using PlatformIO Core (CLI) which will download and install all dependent packages:

# Change directory to PlatformIO Project where is located "platformio.ini"
cd path/to/platformio/project

# Force PlatformIO to install PlatformIO Home dependencies
pio home

# Force PlatformIO to install toolchains
pio run --target upload

If “pio” command is not globally available in your environment and you use PlatformIO IDE, please use built-in PlatformIO Core (CLI) which is located in:

Windows: C:\Users\{username}\.platformio\penv\Scripts\platformio Please replace {username} with a real user name
Unix: ~/.platformio/penv/bin/platformio

Note

You can add platformio and pio commands to your system environment. See Install Shell Commands.

Building

UnicodeWarning: Unicode equal comparison failed

Full warning message is “UnicodeWarning: Unicode equal comparison failed to convert both arguments to Unicode - interpreting them as being unequal”.

KNOWN ISSUE. Please move your project to a folder which full path does not contain non-ASCII chars.

UnicodeDecodeError: Non-ASCII characters found in build environment

KNOWN ISSUE. PlatformIO Core (CLI) currently does not support projects which contain non-ASCII characters (codes) in a full path or depend on the libraries which use non-ASCII characters in their names.

TEMPORARY SOLUTION

Use PlatformIO IDE, it will automatically install PlatformIO Core (CLI) in a root of system disk (%DISK%/.platformio) and avoid an issue when system User contains non-ASCII characters
Do not use non-ASCII characters in project folder name or its parent folders.

Also, if you want to place PlatformIO Core (CLI) in own location, see:

Set PLATFORMIO_CORE_DIR environment variable with own path
Configure custom location per project using core_dir option in “platformio.ini” (Project Configuration File).

ARM toolchain: cc1plus: error while loading shared libraries

See related answers for error while loading shared libraries.

Archlinux: libncurses.so.5: cannot open shared object file

Answered in issue #291.

Monitoring a serial port breaks upload

Answered in issue #384.