Arduino CLI library "not found" / missing include in CI

The sketch includes a library header, but arduino-cli has no matching library installed, so the compiler cannot find the include. Libraries are installed separately from cores and are absent on a clean runner.

What this error means

An arduino-cli compile step fails with a fatal error that an included header was not found, for example "ArduinoJson.h: No such file or directory".

arduino-cli

sketch/blink.ino:1:10: fatal error: ArduinoJson.h: No such file or directory
 #include <ArduinoJson.h>
          ^~~~~~~~~~~~~~~
compilation terminated.

Common causes

The library was never installed

A clean runner has no libraries. Without arduino-cli lib install, the header the sketch includes is not on the include path.

The library name does not match the registry

A misspelled library name, or a name that differs from the registry entry, installs nothing and leaves the include unresolved.

How to fix it

Install the library before compiling

Find the exact registry name with arduino-cli lib search <name>.
Install it with arduino-cli lib install "<name>".
Re-run the compile so the include resolves.

Terminal

arduino-cli lib search ArduinoJson
arduino-cli lib install "ArduinoJson"

Compile with an explicit library path

For a vendored or unpublished library, point the compile at its directory so the header is found.