Docker "buildx bake" Failed in CI

By Kaveh Alemi·Latchkey

docker buildx bake failed while reading or executing the bake definition. The HCL/JSON file is invalid, a named target or variable is undefined, or a target points at a Dockerfile/context that does not resolve.

What this error means

A docker buildx bake <target> exits non-zero with a parse error, target <name> not found, an undefined-variable error, or a downstream build error from one of the baked targets.

docker

ERROR: failed to load bake file: docker-bake.hcl:12,1-7: Unsupported argument;
# or:
ERROR: no such target: relase   (typo of "release")

Diagnose it: build context, cache, or platform?

A Dockerfile that builds locally and fails in CI usually differs in one of three ways: the build context contains different files, the layer cache is cold or poisoned, or the runner architecture does not match what the base image provides.

Terminal

# what is actually being sent as build context (dockerignore applies)
docker build --no-cache --progress=plain -t probe . 2>&1 | head -40

# what platform are you on, and what does the base image support?
docker version --format '{{.Server.Arch}}'
docker buildx imagetools inspect <base-image> | grep -i platform

# prove it is not a cache artefact
docker build --no-cache .

Common causes

Invalid bake HCL/JSON

A syntax error, an unsupported argument, or a malformed block in docker-bake.hcl/.json fails to load before any target runs.

Target or variable not defined

Invoking a target name that is not in the file (often a typo), or referencing an undefined variable, errors out.

A target references an unresolved Dockerfile/context

A target whose dockerfile/context path is wrong fails when bake tries to build it.

How to fix it

Print the resolved bake definition

Use --print to validate the file and see the effective targets before building.

Terminal

docker buildx bake --print
docker buildx bake release

Fix the target name, variables, and paths

Match the invoked target to a defined one and give defaults to variables.

docker-bake.hcl

# docker-bake.hcl
variable "TAG" { default = "1.4.2" }
target "release" {
  context    = "."
  dockerfile = "Dockerfile"
  tags       = ["ghcr.io/myorg/api:${TAG}"]
}

Keep the build context small and deterministic

A missing .dockerignore sends node_modules, .git, and build output to the daemon, which is slow and can change layer hashes between environments.
A COPY of a path that exists locally but is gitignored will fail in CI, because the runner only has what the checkout produced.
Multi-arch builds need buildx and QEMU set up explicitly; a plain docker build on an ARM runner silently produces an ARM image.

How to prevent it

Validate bake files with --print in CI before building.
Default bake variables so missing inputs do not error.
Keep target names and Dockerfile/context paths in sync with the file.

Frequently asked questions

What causes Docker "buildx bake" failed in CI?

There are 3 common causes: invalid bake hcl/json, target or variable not defined, and a target references an unresolved dockerfile/context. A syntax error, an unsupported argument, or a malformed block in docker-bake.hcl/.json fails to load before any target runs.

How do I fix Docker "buildx bake" failed in CI?

There are 2 fixes depending on which cause you have: print the resolved bake definition and fix the target name, variables, and paths. Work through them in order, since the first is the most common.

What does Docker "buildx bake" failed in CI actually mean?

A docker buildx bake <target> exits non-zero with a parse error, target <name> not found, an undefined-variable error, or a downstream build error from one of the baked targets.

How do I stop Docker "buildx bake" failed in CI happening again?

Validate bake files with --print in CI before building. The prevention section lists 3 changes that keep it from recurring.