CMake build "fatal error: X.h: No such file or directory" in CI

The compiler could not find an included header on any of its include paths. Either the target_include_directories entry is missing, or the system -dev package that ships the header is not installed on the runner.

What this error means

A compile step fails with "fatal error: openssl/ssl.h: No such file or directory" for a header that resolves fine on a developer machine with the -dev package present.

cmake

/home/runner/work/app/app/src/tls.cpp:3:10: fatal error: openssl/ssl.h: No such file
or directory
    3 | #include <openssl/ssl.h>
      |          ^~~~~~~~~~~~~~~
compilation terminated.

Common causes

The -dev package with the header is not installed

The runtime library may be present, but the header lives in the -dev package that a slim runner omits.

The include directory is not on the target

The header exists but its directory was never added with target_include_directories or via find_package.

How to fix it

Install the -dev package that ships the header

Install the development package so the header is on the default include path.

Terminal

sudo apt-get update
sudo apt-get install -y libssl-dev
cmake --build build

Add the include directory to the target

When you own the header, expose its directory through target_include_directories.

CMakeLists.txt

target_include_directories(app PRIVATE ${CMAKE_SOURCE_DIR}/include)

How to prevent it

Install every dependency's -dev package in a setup step.
Prefer find_package targets that carry include dirs automatically.
Keep target_include_directories in sync with the source layout.