Bazel C++ "undeclared inclusion(s)" error in CI

By Daniel Zoghalchali·Latchkey

Bazel enforces that every header a C++ rule includes is declared in that rule or one of its deps. When a source includes a header that is not declared, Bazel reports "undeclared inclusion(s) in rule" to keep builds hermetic and cache-correct.

What this error means

A cc_library or cc_binary build fails with "this rule is missing dependency declarations for the following files included by X" listing the undeclared headers.

ERROR: .../BUILD:3:11: undeclared inclusion(s) in rule '//src:app':
this rule is missing dependency declarations for the following files included by 'src/app.cc':
  'src/util.h'

Common causes

A header not listed in hdrs/srcs or a dep

The source includes a header that belongs to another target but that target is not in deps, or the header is not in this rule's hdrs.

A system header outside the declared toolchain

A header from a system path the toolchain does not declare (a misconfigured cxx_builtin_include_directories) is included without declaration.

How to fix it

Declare the header

Add the header to the rule's hdrs or add the providing target to deps.

cc_library(
    name = "util",
    hdrs = ["util.h"],
)
cc_binary(
    name = "app",
    srcs = ["app.cc"],
    deps = [":util"],
)

Fix the toolchain builtin include dirs

If the header is a system one, ensure the C++ toolchain declares its directory so Bazel treats it as builtin.

# in the toolchain config
cxx_builtin_include_directories = ["/usr/include", "/usr/lib/gcc/..."]

How to prevent it

• Declare every included header in hdrs or via a dep.
• Keep the C++ toolchain builtin include directories accurate on CI images.
• Run bazel build locally so undeclared inclusions surface before CI.

Frequently asked questions

Related guides

References

• CMake documentation
• GitHub Actions documentation