Environment Switching Requires .pio Cleanup on Windows

Author: sylqueCreated Jan 8, 2026Updated Sep 5, 2026

Labelshelp wantedbuild system

Problem Summary

When switching between build environments on Windows (but not WSL), PlatformIO fails to compile with "No such file or directory" errors for library headers. The issue requires deleting the environment-specific libdeps directories.

Environment

OS: Windows. Issue does NOT occur on WSL.
Platform: ESP32 (espressif32)
Board: M5Stack StampS3
Framework: Arduino
PlatformIO Configuration: See below

Steps to Reproduce

Delete the .pio folder (clean state)
Select environment release
Build → ✅ Compiles successfully
Switch to environment debug

Build → ❌ Fails with header file errors like:

foo.cpp:7:10: fatal error: bar.h: No such file or directory

Note: This occurs with any environment switch (debug ↔ release, debug ↔ debugNoBle, etc.)

Current Workarounds Tested

Deleting .pio/libdeps/debug → Fixes the issue

Configuration Details

Full platformio.ini

ini

[platformio]
default_envs = debug
build_cache_dir = ${platformio.core_dir}/build_cache

##################################################

[env]
platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.35/platform-espressif32.zip
board = m5stack-stamps3
framework = arduino
monitor_speed = 115200
board_build.partitions = huge_app.csv
monitor_filters = esp32_exception_decoder
build_unflags = 
  -Os
  -Werror=all
  -std=gnu++2a 
  -std=gnu++2b
  -fno-rtti
build_flags = 
  -std=gnu++23
  -I".pio/libdeps/${PIOENV}/M5Unified/src" ; Required for lib_ldf_mode = off
  -I".pio/libdeps/${PIOENV}/M5GFX/src" ; Required for lib_ldf_mode = off
  -I"${platformio.packages_dir}/framework-arduinoespressif32/libraries/Wire/src" ; Required for lib_ldf_mode = off
  -I"${platformio.packages_dir}/framework-arduinoespressif32/libraries/SPI/src" ; Required for lib_ldf_mode = off
  -I"${platformio.packages_dir}/framework-arduinoespressif32/libraries/Preferences/src" ; Required for lib_ldf_mode = off
lib_deps = 
  symlink://../../../AzzLibs/ImuTools
  symlink://../../CapsuleComponents
  Wire ; Required for lib_ldf_mode = off
  SPI ; Required for lib_ldf_mode = off
  Preferences ; Required for lib_ldf_mode = off
lib_ldf_mode = off

##################################################

[ble]
lib_deps = 
  symlink://../../../AzzLibs/BleTasksForSlAndSp
build_src_filter = +<*> -<.git/> -<.svn/> -<old/>
build_flags = 
  -D ENABLE_BLE=true

[noBle]
lib_deps = 
  symlink://../../../AzzProtocol/lib_cpp
  symlink://../../../AzzLibs/NetVar
  symlink://../../../AzzLibs/Os
build_src_filter = +<*> -<.git/> -<.svn/> -<tasks/BleTask.cpp> -<old/>
build_flags = 
  -D ENABLE_BLE=false 

##################################################

[debug]
build_type = debug
build_flags = 

[release]
build_type = release
build_flags = 
  -DNDEBUG 
  -O3
  
##################################################

[env:debug]
extends = debug
lib_deps = ${env.lib_deps} ${ble.lib_deps}
build_flags = ${env.build_flags} ${ble.build_flags} ${debug.build_flags}
build_src_filter = ${ble.build_src_filter}

[env:debugNoBle]
extends = debug
lib_deps = ${env.lib_deps} ${noBle.lib_deps}
build_flags = ${env.build_flags} ${noBle.build_flags} ${debug.build_flags}
build_src_filter = ${noBle.build_src_filter}

[env:release]
extends = release
lib_deps = ${env.lib_deps} ${ble.lib_deps}
build_flags = ${env.build_flags} ${ble.build_flags} ${release.build_flags}
build_src_filter = ${ble.build_src_filter}

##################################################

Additional Context

This environment switching issue is part of a long-standing pattern of .pio folder corruption on Windows that significantly impacts development productivity, requiring frequent manual cleanup.

Source: platformio/platformio-core

View original on GitHub View discussion on GitHub