How to fix Bazel “no matching toolchains found”
Bazel could not find a registered toolchain whose type and constraints satisfy the target and execution platform requirements.
Common causes
- The required toolchain was not registered
- Constraint values differ between toolchain and platform declarations
- Repository or module registration is missing
- The selected execution platform excludes every candidate
What to check
- Run the failing command with --toolchain_resolution_debug=regex (use .* for all resolution details)
- List registered execution platforms and their constraints
- Compare target, execution-platform, and toolchain compatibility constraints
- Check WORKSPACE or MODULE.bazel registration and visibility
Step-by-step toolchain troubleshooting
Resolve this Bazel analysis failure by checking registration and platform compatibility. Start with the failing target and its original flags; changing the target platform can hide the mismatch without fixing the intended build.
1. Capture resolution diagnostics
Replace the example target with yours and keep your usual build flags:
bazel build //app:server --toolchain_resolution_debug='.*'Find the required toolchain type and the candidates rejected for it. Distinguish a missing registration from a registered toolchain rejected by platform constraints.
2. Fix the rejected candidate
If the required toolchain is absent, follow the rule set’s setup instructions and register its toolchain target in MODULE.bazel. Legacy WORKSPACE projects must use the setup supported by their Bazel version. Register the toolchain declaration, not an arbitrary compiler executable.
If a candidate exists, compare its target_compatible_with constraints with the target platform and its exec_compatible_with constraints with the execution platform. These describe different machines: where the output runs versus where the build tool runs.
Worked example: Linux execution from a Mac
Suppose your remote build uses Linux x86-64 workers, but the registered compiler toolchain only supports macOS execution. Register a compiler toolchain that can actually run on Linux x86-64 and make the matching execution platform available to Bazel. Keep the target constraints appropriate for the output you intend to build. Do not relabel a macOS compiler as Linux-compatible.
3. Verify the repair
Rerun the same target and flags with resolution diagnostics enabled. Confirm that Bazel selects the intended toolchain and proceeds beyond analysis. If execution then fails, investigate that separately; selecting a toolchain does not prove its compiler or remote worker environment works.
Primary sources
Use these references to confirm protocol and version-specific behavior.
Investigate with build-level evidence
Hermetiq correlates Bazel actions, cache behavior, Buildbarn infrastructure, and remote-execution timing so teams can move from a status code to the build and system behavior behind it.
Technical review: Sep 23, 2026 · Verify flags and behavior against the Bazel and Buildbarn versions deployed in your environment.