The Mechanic
How Bazel works under the hood
Understand the mechanisms behind Bazel's behavior: graph reachability, phases, hermetic actions, cache identity, and execution strategies. Use that model to diagnose ordinary build surprises.
Level 2 opens the machine enough to make ordinary Bazel surprises diagnosable. A narrow build, a sandbox failure, a cache miss, and a strategy flag are not one generic class of "Bazel weirdness". They belong to different layers of the system.
Place Each Symptom In A System Layer
Start with the shape of the request. 2.1 Directed Acyclic Graph (DAG) explains why a command begins from a target and follows dependency edges through a reachable slice instead of sweeping the whole repository. That graph is the first reason small requests can stay small.
Then split one command into responsibilities. 2.2 Three Phases of a Build separates loading, analysis, and execution, which makes logs easier to read: some failures happen while Bazel is reading declarations, others while it is planning actions, and others only after tools actually run.
The execution side has its own contract. 2.3 Hermeticity & Sandboxing asks whether an action's real inputs match what Bazel recorded. 2.4 Caching & Incrementality explains how Bazel decides which remembered values are still valid. 2.5 Execution Strategies then names where and how already-planned actions run: local, sandboxed, worker, remote, or dynamic.
Diagnose By Symptom
Read the level in order if the internals are new. If you are debugging a live issue, jump by symptom: broad target sets to 2.1 Directed Acyclic Graph (DAG), confusing logs to 2.2 Three Phases of a Build, sandbox or CI-only failures to 2.3 Hermeticity & Sandboxing, unexpected rebuilds to 2.4 Caching & Incrementality, and strategy-flag advice to 2.5 Execution Strategies.
A first diagnosis places the request in its reachable graph and distinguishes loading, analysis, execution, hermeticity, reuse, and strategy concerns. Naming that layer turns generic “Bazel weirdness” into a hypothesis that evidence can test.
Next: turn those mechanics into shared repository policy, beginning with 3.1 Dependency Management.
