4.6.3 Toolchain Resolution

Toolchain resolution is the analysis-phase algorithm that turns a rule's declared toolchain type into one concrete ToolchainInfo provider for the current target. The rule says "I need a //glyph/toolchains:toolchain_type" and Bazel picks the registered toolchain() whose constraints match both the target platform and an available execution platform.¹ The framework from 4.6.2 Defining, Registering & Accessing Toolchains sets the table. Resolution decides who sits at it.

This is where the target-vs-execution split from 4.6.1 Platform Model for Rule Authors becomes mechanical. A toolchain that can target the requested platform but cannot run on any available executor is rejected. So is a toolchain that runs everywhere but does not produce code for the requested target. Rule authors do not call this algorithm. They design rules that depend on its outcome.

What Goes In

Resolution takes four inputs per target:²

• the set of toolchain types the rule declared in rule(toolchains = [...]),
• the target platform (set by --platforms or inherited),
• the list of available execution platforms,
• the list of available toolchain() candidates for those types.

Available execution platforms and toolchains are gathered from register_execution_platforms() and register_toolchains() in the transitive MODULE.bazel graph, plus --extra_execution_platforms and --extra_toolchains on the command line. The host platform is always included as an execution platform candidate.²

A rule's exec_compatible_with (on the rule definition or the target) further filters available execution platforms before resolution starts. Toolchains that declare target_settings are dropped if those settings do not match the current configuration.³

Order is part of the input. In Bazel 9, Bazel builds one ordered candidate list from these sources:²

1. --extra_toolchains candidates have highest priority. The last repeated flag entry wins.
2. register_toolchains() entries come from the resolved Bzlmod graph.
3. Root-module registrations precede dependency-module registrations.
4. Within register_toolchains() ordering, the first compatible candidate wins.
5. Expanded target patterns are deterministic: toolchains in subpackages register before those in the parent package, and targets within one package register in lexicographic order.²

The place a toolchain() target is physically defined does not determine this priority. Its registration entry mechanism does: a target defined in a dependency repository can still enter first through the root module's register_toolchains(), for example. Bazel does not expose a browsable global registry. It assembles this ordered candidate list as an input to resolution. If you ask "why did Bazel pick this toolchain?", start with the list and each entry's provenance.

The Two-Pass Algorithm

Resolution is presented as a single step, but it splits cleanly into two passes that are easier to reason about:⁵ one toolchain type at a time, then one target at a time.

First Pass: Per-Execution-Platform Assignment

For one toolchain type, filter the ordered candidate list to registered toolchain() targets that declare that type, preserving order. Reject a candidate that cannot target the target platform. For each remaining candidate, scan execution platforms. If a platform has no assignment yet and the candidate can run there, assign its toolchain implementation target. The result is a map: {exec_platform → implementation target} for that single type.⁵ First compatible candidate wins per execution platform. Repeat the same pass independently for every requested type.

The matching rule is straightforward: a target_compatible_with or exec_compatible_with clause matches a platform when every constraint_value in the clause is also on the platform. Constraint values that the platform has from settings the clause does not mention are ignored.⁶

Selection Stage: Pick One Execution Platform

A target may need several toolchain types (e.g., a Java toolchain plus a runtime), some mandatory and some optional via config_common.toolchain_type(..., mandatory = False).⁷ The selection stage picks one execution platform that satisfies every mandatory type and gets the best optional coverage.

Drop any execution platform that failed to find a mandatory toolchain in the first pass. Among the survivors, prefer the platform with the most resolved toolchain types. Because all survivors have the mandatory types, optional toolchains decide the count. Execution-platform registration order breaks ties.⁸ That platform becomes the target's execution platform, and its associated toolchains become the target's dependencies.

The chosen execution platform is then used for every action the target generates — unless the rule uses 4.6.5 Execution Groups & Auto Exec Groups, in which case each exec group runs both resolution stages independently and ends up with its own execution platform and toolchain set.⁹

Order Matters In Practice

Two different lists drive the two stages. The first pass walks the ordered candidate list assembled from --extra_toolchains and the resolved Bzlmod graph. The selection stage preserves execution-platform registration order (from register_execution_platforms() and --extra_execution_platforms).⁵ Mixing them up is the most common reason "the same MODULE.bazel picks differently than I expected."

A practical consequence: if multiple toolchains for the same type can target the same platform and run on the same executor, the first compatible candidate in the ordered candidate list wins — there is no "best fit" scoring. Rulesets that want a deterministic default usually publish their toolchains in a fixed order from a single register_toolchains() call. The rules_glyph MODULE.bazel is the minimal end of that spectrum: one registered toolchain() that resolves cleanly for the host — the success case behind the failure snippet below.

When Resolution Fails

Resolution failure is an analysis-phase error, not a configuration warning. A mandatory toolchain type with no compatible candidate halts analysis with a message like this:¹⁰

demo_rule(
    name = "demo",
)

ERROR: BUILD.bazel:3:10: While resolving toolchains for target //:demo (680dcaf): No matching toolchains found for types:
  //toolchain:demo_toolchain_type
To debug, rerun with --toolchain_resolution_debug='//toolchain:demo_toolchain_type'

That output comes from a workspace that defines a rule with toolchains = ["//toolchain:demo_toolchain_type"] but never registers any concrete toolchain — reproduce it with snippets/toolchain-resolution-error. The fix is almost always one of three things: register the toolchain, relax exec_compatible_with / target_compatible_with, or declare the toolchain optional.⁷

Reproduce this error

Optional toolchains keep analysis alive: when no candidate matches, ctx.toolchains["//pkg:toolchain_type"] returns None instead of failing.⁷ That is the right call when a rule can degrade gracefully and the wrong call when the missing tool would cause a confusing failure later.

Debugging A Real Resolution

Three tools cover most resolution debugging:

--toolchain_resolution_debug=<regex> prints what Bazel considered. The flag takes a regex matched against toolchain types and target labels. .* prints everything.¹¹ Bazel 7 restructured this output: one message per algorithm invocation, indentation that mirrors the loop, and early stopping when every execution platform has an assignment.⁵ The same flag now produces something readable instead of an expert-only wall of text.

For the failing snippet above, --toolchain_resolution_debug='//toolchain:demo_toolchain_type' shows the per-platform check directly:

INFO: ToolchainResolution: Performing resolution of //toolchain:demo_toolchain_type for target platform @@platforms//host:host
      ToolchainResolution: No //toolchain:demo_toolchain_type toolchain found for target platform @@platforms//host:host.

bazel cquery 'deps(//x:y, 1)' --transitions=lite answers "which of these dependencies came from toolchain resolution?" The transitions output tags toolchain dependencies and shows the configuration each one runs under, separating implicit toolchain edges from rule attributes you wrote.¹² 5.2.2 bazel cquery — Configured Graph is the dedicated chapter on the tool itself. Here it is the most direct way to see what the selection stage actually picked.

bazel config <hash> inspects the resolved configuration of a specific configured target — useful when two configurations of the same toolchain show up in cquery output and you need to know what differs between them. 5.2.4 bazel config — Configuration Inspection is the home of that workflow.

These commands are a starting point, not a complete diagnosis. 5.6.4 Toolchain Resolution Debugging gives the complete workflow for keeping one trace attached to the right configured target, comparing constraints on the correct axis, and confirming the resolved dependency.

Why The Indirection Is Worth It

Toolchain resolution is the mechanism that lets P.2.3 Core vs Rulesets actually work. Bazel Core never hardcodes which compiler runs for a given language. It gives rule authors an interface, gives users a registration list, and resolves the two at analysis time based on platform constraints. The selected toolchain is an implicit configured-target dependency in analysis, so rule implementations do not enumerate candidates and BUILD target authors do not choose a concrete implementation. Its files become action inputs or tools only when the rule registers an action that supplies them. That action declaration is what ordinary caching and remote execution see.

That indirection is also why "no matching toolchains found" is usually a registration or constraint problem rather than a code problem. The algorithm itself is small, deterministic, and order-driven. Once you can read the debug output for one execution platform, the rest scales.