Bazel Hermetic Toolchain Not Found - Fix Non-Hermetic Builds in CI

By Daniel Zoghalchali·Latchkey

A hermetic build registers its own pinned toolchains (compiler, JDK, Python, Node) so it does not depend on whatever the runner happens to have. When a toolchain is unregistered, Bazel either falls back to a missing host tool or reports "no matching toolchains".

What this error means

A build that passes on a developer machine fails on a clean CI runner with "no matching toolchains" or a missing host compiler/SDK. The difference is the local machine had the tool installed; the hermetic runner does not.

Bazel output

ERROR: While resolving toolchains for target //svc:bin:
  no matching toolchains found for types @bazel_tools//tools/cpp:toolchain_type
  (host has no cc; register a hermetic C++ toolchain)

Diagnose it: task graph and workspace resolution

Terminal

npx turbo run build --dry-run=json | head -40
npx nx graph --file=graph.json
pnpm -r list --depth -1 2>/dev/null || yarn workspaces list

Common causes

Toolchain not registered

Without registering a hermetic toolchain (e.g. hermetic_cc_toolchain, rules_java’s JDK, a pinned Python), Bazel has no toolchain matching the action’s type on a bare runner.

Build relies on host tools

The build implicitly used the developer’s system compiler/SDK; the CI runner is minimal and lacks it, exposing the non-hermeticity.

How to fix it

Register a hermetic toolchain

Pin the toolchain so the build provides its own compiler/SDK rather than depending on the host.

MODULE.bazel

# MODULE.bazel
bazel_dep(name = "toolchains_llvm", version = "1.0.0")
llvm = use_extension("@toolchains_llvm//toolchain/extensions:llvm.bzl", "llvm")
llvm.toolchain(llvm_version = "17.0.6")
use_repo(llvm, "llvm_toolchain")
register_toolchains("@llvm_toolchain//:all")

Verify toolchain resolution

Terminal

bazel cquery 'deps(//svc:bin)' --toolchain_resolution_debug='.*'

How to prevent it

Register pinned hermetic toolchains for every language you build.
Run CI on a minimal image so host-tool reliance surfaces early.
Use --toolchain_resolution_debug to confirm hermetic toolchains apply.

Frequently asked questions

What causes Bazel hermetic toolchain not found?

There are 2 common causes: toolchain not registered and build relies on host tools. Without registering a hermetic toolchain (e.g.

How do I fix Bazel hermetic toolchain not found?

There are 2 fixes depending on which cause you have: register a hermetic toolchain and verify toolchain resolution. Work through them in order, since the first is the most common.

What does Bazel hermetic toolchain not found actually mean?

A build that passes on a developer machine fails on a clean CI runner with "no matching toolchains" or a missing host compiler/SDK.

How do I stop Bazel hermetic toolchain not found happening again?

Register pinned hermetic toolchains for every language you build. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation