The operating manual for Bazel and Buildbarn.
Start from specific errors, improve cache and remote execution, understand build telemetry, and find the next useful check—without guessing from logs.
What do you need to do?
Choose the route closest to the problem in front of you.
Start from the status code or failure text and work toward the responsible layer.
Browse error reference →02Explain a cache missCompare the key-forming inputs behind equivalent actions and machines.
Open cache workflow →03Unblock remote executionSeparate queueing, worker capacity, transfers, execution, and storage.
Open RBE workflow →04Understand build telemetryStart with Bazel’s primary documentation for the Build Event Protocol.
Open the BEP reference ↗Move from symptom to verified improvement.
Each path keeps related explanations and investigations in a deliberate order.
Improve Bazel performance
Establish a baseline, find repeated work, and separate build-graph constraints from infrastructure constraints.
Debug remote-cache misses
Move from an aggregate hit rate to the key-forming fields that differ between comparable actions.
Operate Buildbarn and RBE
Understand the scheduler, worker, storage, queue, and transfer layers—and how they affect individual builds.
Start from the failure you can see.
Every entry distinguishes what the status means from the possible causes you still need to verify.
Diagnose DEADLINE_EXCEEDED errors from Bazel remote execution by separating client, queue, worker, transfer, and action timeouts.
Open resource →Bazel remote cache UNAVAILABLETroubleshoot Bazel remote cache UNAVAILABLE errors across DNS, TLS, proxies, storage, overload, and transient connectivity.
Open resource →Buildbarn action stuck in queueDiagnose Buildbarn actions stuck in scheduler queues by checking platform matching, worker capacity, size classes, and worker health.
Open resource →Buildbarn CAS NOT_FOUNDInvestigate Buildbarn CAS NOT_FOUND errors involving missing input blobs, eviction, replication, upload races, and storage configuration.
Open resource →Bazel “no matching toolchains found”Fix Bazel toolchain resolution failures by inspecting registered toolchains, constraints, execution platforms, and resolution diagnostics.
Open resource →Bazel cache misses across machinesDiagnose Bazel remote-cache misses between developer machines and CI by comparing action inputs, commands, environments, platforms, and toolchains.
Open resource →Buildbarn worker not receiving actionsTroubleshoot Buildbarn workers that register but receive no actions by checking scheduler connectivity, platform queues, size classes, and demand.
Open resource →Bazel action key changed unexpectedlyFind why a Bazel action key changed by comparing declared inputs, command arguments, environment variables, tools, and platform properties.
Open resource →Reviewed paths, tools, and primary sources.
Measure the critical path, repeated work, and remote-execution phases before choosing an optimization.
Open resource →Remote-cache troubleshooting pathMove from an aggregate hit rate to comparable actions, key-forming fields, and a cause you can verify.
Open resource →Buildbarn and RBE operations pathTrace work through scheduling, platform routing, workers, storage, transfers, and execution.
Open resource →Compare two Bazel action recordsUse a client-side JSON diff to narrow down changed action fields. The tool does not submit pasted JSON to Hermetiq.
Open resource →Bazel remote-caching documentationOfficial configuration, protocol, authentication, and troubleshooting guidance for Bazel remote caching.
Open resource →Buildbarn remote-execution sourceThe maintained scheduler, worker, and runner implementation—the authoritative reference for component behavior.
Open resource →Remote Execution API specificationThe protocol contract for actions, operations, execution, content-addressable storage, and status handling.
Open resource →Bazel Build Event Protocol documentationOfficial documentation for Bazel’s structured build-event graph, transports, and event consumption.
Open resource →gRPC status-code referenceCanonical meanings for DEADLINE_EXCEEDED, UNAVAILABLE, NOT_FOUND, and other RPC statuses.
Open resource →Technical content should show its work.
Hermetiq troubleshooting references link to primary Bazel, Buildbarn, REAPI, or gRPC sources and show a technical-review date. We separate protocol meaning from likely causes, state important limitations, and avoid universal performance thresholds.
Behavior can differ by Bazel, Buildbarn, proxy, and deployment version. Verify flags and configuration against the versions running in your environment.
Report an error or request a correction →