Missing header in CMake builds: diagnose include path failures

Recognizable condition

The build fails with a compiler error like fatal error: header.h: No such file or directory even though header.h exists in the source tree. The error appears for a specific target or only in certain configurations, and the file is included with a relative path such as #include \"header.h\" or #include <header.h>.

The useful takeaway is that the compiler is invoked without an -I flag that points to the directory containing the header. In CMake this means the target's include interface is incomplete or not propagated to the consumer.

Cause to symptom table

Ordered checks

Run these checks in order from the build system outward. Work in the build directory where CMake generated the files. No elevated permissions are required, only read access to source and build trees.

1. Confirm the compile command

Re-run configuration to ensure the build system is fresh, then inspect the actual compiler invocation.

cmake -S <source_dir> -B <build_dir> -DCMAKE_BUILD_TYPE=Release
cmake --build <build_dir> --target <target> -v

With Make generators use make VERBOSE=1 in <build_dir>. With Ninja use ninja -v. Look for -I flags. Expected check: the directory containing the header appears in the -I list for the failing translation unit. Risk: verbose output is long; filter with | grep <target>.

2. Inspect target include interface

In the source tree locate the CMakeLists.txt that defines the failing target. Check how includes are added.

target_include_directories(<target> PRIVATE <dir>)

PRIVATE adds the directory for the target's own sources only. PUBLIC and INTERFACE propagate to consumers. For an interface library, only INTERFACE or PUBLIC makes the path visible.

3. Check propagation through dependencies

If the header is provided by a dependency library, verify the usage requirement.

target_link_libraries(<consumer> PRIVATE <provider>)

With PRIVATE linkage, usage requirements from <provider> are not propagated further. Use PUBLIC or INTERFACE when the consumer needs the headers.

4. Check cache and environment overrides

Run:

cmake -LAH <build_dir> | grep -i include

Look for CMAKE_INCLUDE_PATH or user-set variables that point to a non-existent directory. These variables are global and can override per-target settings. Changing them in the cache with -D or ccmake affects all targets and harms portability.

5. Check generator expressions

Find uses of generator expressions in include directories, e.g.:

target_include_directories(<target> PRIVATE $<$<CONFIG:Debug>:$<TARGET_PROPERTY:DEBUG_INCLUDE_DIR>>)

If the expression evaluates to empty for the active configuration, the include path disappears. Verify the expression by printing the target property after configure.

Fixes tied to findings

Source directory not included

Add the directory explicitly. For a target app with sources in src:

target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)

Use CMAKE_CURRENT_SOURCE_DIR not a relative path. This is needed for out-of-source builds where the compiler runs from the build tree.

Include not propagated to consumer

Change scope from PRIVATE to PUBLIC if the header is needed by users of the library:

target_include_directories(mylib PUBLIC include)

For an interface library that only provides headers:

add_library(headers INTERFACE)
target_include_directories(headers INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/include)

Consumers then link to headers. Do not use PRIVATE for an interface library.

Cache override or bad path

Remove the offending cache entry and rely on target properties. If a variable must be set, set it per-target, not globally. Avoid editing the cache directly unless you understand the effect on all targets.

Generator expression empty

Simplify the expression or provide a fallback. Ensure the property is set for all configurations you build. Test the expression by configuring for each configuration you support.

Verify the fix

Re-run configuration and build:

cmake -S <source_dir> -B <build_dir>
cmake --build <build_dir> --target <target>

Check that the compile command now contains the expected -I flag for the header directory. Build the target again; the missing-header error should be gone and object files should be produced. If using an IDE, refresh the CMake project and verify include paths appear in project settings or IntelliSense configuration.

Limitation: CMake does not warn when an include directory does not exist. A non-existent path is silently passed to the compiler, so always verify existence of the directory referenced in target_include_directories.

When to escalate

Escalate if the include path is correct in the compile command but the header is still not found. Possible causes outside CMake: incorrect include syntax in source, header guarded by a preprocessor condition, or a custom command that compiles files outside the CMake target.

Escalate if multiple targets share a common include and changing scope breaks other consumers. This indicates a design issue with header visibility that requires a refactor of PUBLIC vs PRIVATE boundaries.

Escalate if the problem appears only on a CI machine. Compare cache variables and environment between local and CI, and check for case sensitivity differences on filesystems.