how to debug docker buildx bake failures

TL;DR

Bake failures usually live in one of three places: the HCL file (variable interpolation and target inheritance), the builder instance (wrong driver or missing features), or the difference between what bake passes and what a plain build does. Validate the bake file first with a print of the resolved targets, then reproduce with a plain build of one target to isolate the layer.

The query

how to debug docker buildx bake failures

Use this when

• docker buildx bake fails with unclear errors
• Targets inherit unexpected settings
• Bake behaves differently than docker build
• HCL variables do not resolve as expected

Not for when

• Plain Dockerfile build errors (debug those directly)
• Pushing to registries (auth and network, different topic)
• BuildKit daemon issues unrelated to bake

Steps

Step 1: Print the resolved bake targets

Use bake's print action to dump the fully resolved configuration for your targets. This shows exactly what bake will pass to the builder: contexts, args, tags, platforms. Most HCL surprises (wrong variable, bad inheritance) are visible here. Expected output: the resolved target definitions, revealing any misconfiguration before a build runs.

Step 2: Validate the HCL file syntax and variables

Check variable definitions, default values, and interpolation. Undefined variables and type mismatches fail in confusing ways. Keep the bake file small and explicit while debugging; inline complexity hides errors. Expected output: a clean print with no warnings about variables or overrides.

Step 3: Reproduce with a single plain build

Take one failing target's resolved settings and run it as a plain docker buildx build with the same args and context. If the plain build fails too, the problem is the Dockerfile or context, not bake. Expected output: isolation of the failure to bake configuration vs the actual build.

Step 4: Check the builder instance capabilities

Verify the builder driver supports what the bake file asks for: multi-platform needs the right driver, certain cache exporters need specific setups. An underpowered default builder explains failures that look like bake bugs. Expected output: builder features matching the bake file's requirements, or the builder upgraded/created accordingly.

Step 5: Bisect the targets

If multiple targets fail, run them one at a time to find the first failure. Bake runs targets with shared state; one bad target can poison the output for others. Fix them in dependency order. Expected output: the single target (and setting) responsible, with the rest building cleanly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstU7hbiaNbVtUNm6ZlXP5Kw