Fatal error: <somelib.h>: No such file or directory. Another weird, reoccurring include problem

This might be the most asked about issue on this forum: You create/modify a project and suddenly a library is not found anymore.

This frustrating error occurs to many and its solutions are way more specific than the error itself. I hope to uncover the reason(s) behind this in the following topic with the help of the platformIO-team.

Details:

OS: Windows 10
PlatformIO: v2.5.1
Project: AZ-Delivery Kit ESP32

The problem:

LiquidCrystal_I2C.h: No such file or directory

Logs:

 *  Executing task in folder ESP32_P2P_Reciever: C:\Users\J\.platformio\penv\Scripts\platformio.exe run 

Processing az-delivery-devkit-v4 (platform: espressif32; board: az-delivery-devkit-v4; framework: arduino)
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/espressif32/az-delivery-devkit-v4.html
PLATFORM: Espressif 32 (3.3.2) > AZ-Delivery ESP-32 Dev Kit C V4
HARDWARE: ESP32 240MHz, 520KB RAM, 16MB Flash
DEBUG: Current (esp-prog) External (esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
PACKAGES:
 - framework-arduinoespressif32 @ 3.10006.210326 (1.0.6)
 - tool-esptoolpy @ 1.30100.210531 (3.1.0)
 - toolchain-xtensa32 @ 2.50200.97 (5.2.0)
LDF: Library Dependency Finder -> https://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 33 compatible libraries
Scanning dependencies...
Dependency Graph
|-- LiquidCrystal_I2C @ 1.1.4
|   |-- Wire @ 1.0.1
|-- requests
|-- hardware
|   |-- mailbox
|   |   |-- requests
|   |-- general
|   |   |-- mailbox
|   |   |   |-- requests
|   |   |-- requests
|   |   |-- WebServer @ 1.0
|   |   |   |-- WiFi @ 1.0
|   |   |   |-- FS @ 1.0
|   |   |-- WiFi @ 1.0
|   |-- requests
|   |-- LiquidCrystal_I2C @ 1.1.4
|   |   |-- Wire @ 1.0.1
|-- mailbox
|   |-- requests
|-- general
|   |-- mailbox
|   |   |-- requests
|   |-- requests
|   |-- WebServer @ 1.0
|   |   |-- WiFi @ 1.0
|   |   |-- FS @ 1.0
|   |-- WiFi @ 1.0
|-- WebServer @ 1.0
|   |-- WiFi @ 1.0
|   |-- FS @ 1.0
Building in release mode
Compiling .pio\build\az-delivery-devkit-v4\src\main.cpp.o
Generating partitions .pio\build\az-delivery-devkit-v4\partitions.bin
Compiling .pio\build\az-delivery-devkit-v4\lib438\Wire\Wire.cpp.o
Compiling .pio\build\az-delivery-devkit-v4\libb63\LiquidCrystal_I2C\LiquidCrystal_I2C.cpp.o
Compiling .pio\build\az-delivery-devkit-v4\libe87\requests\rq_handler.cpp.o
In file included from lib\requests\rq_handler.cpp:15:0:
lib\hardware/lcd.h:5:31: fatal error: LiquidCrystal_I2C.h: No such file or directory

***************************************************************************
* Looking for LiquidCrystal_I2C.h dependency? Check our library registry!
*
* CLI  > platformio lib search "header:LiquidCrystal_I2C.h"
* Web  > https://registry.platformio.org/search?q=header:LiquidCrystal_I2C.h
*
***************************************************************************

compilation terminated.
*** [.pio\build\az-delivery-devkit-v4\libe87\requests\rq_handler.cpp.o] Error 1
============================================================================================ [FAILED] Took 5.95 seconds ============================================================================================

 *  The terminal process "C:\Users\J\.platformio\penv\Scripts\platformio.exe 'run'" terminated with exit code: 1. 
 *  Terminal will be reused by tasks, press any key to close it.

platformio.ini:

[env:az-delivery-devkit-v4]
platform = espressif32
board = az-delivery-devkit-v4
framework = arduino
monitor_speed = 115200
upload_port = COM4
monitor_port = COM4
lib_deps = marcoschwartz/LiquidCrystal_I2C@^1.1.4
debug_tool = esp-prog
debug_init_break = tbreak setup

What I tried:

  • Clean
  • Delete .pio-folder
  • Reinstall LiquidCrystal_I2C-lib

Very weird behaviour:

<LiquidCrystal_I2C.h> is called in one custom header-file in a subfolder of the lib-folder. The first few lines of this file look like this:

#ifndef _LCD_H_
#define _LCD_H_

#include <Arduino.h>
#include <LiquidCrystal_I2C.h>

#define ...

If i now choose to include another lib which is installed per default, i get the same error but now it can’t find Wire.h:

#ifndef _LCD_H_
#define _LCD_H_

#include <Arduino.h>
#include <Wire.h> // add Wire.h
#include <LiquidCrystal_I2C.h>

#define ...

I hope we can cooperate and settle the following questions:

  • Why do seemingly existent libs not get picked up
  • Is this just a C-inclusion issue and PlatformIO is leaving a misleading error message
  • What could be a valid debug-method other than “clean+delete .pio” which people facing the same issue can use to get a better understanding of this?

Thank you for an otherwise great platform which has accellerated my coding speed, quality and style.