buildx bake "failed to load bake definition" / HCL file not found in CI

By Kaveh Alemi·Latchkey

buildx bake reads its targets from a bake file (docker-bake.hcl, docker-bake.json, or a compose file). If the file passed to -f does not exist at the working directory, bake fails before evaluating any target.

What this error means

A docker buildx bake step fails with "failed to load <file>: no such file or directory" or "couldn't find a bake definition file".

ERROR: failed to load docker-bake.hcl: no such file or directory

Common causes

Wrong working directory for the bake file

bake looks for the definition relative to the job's working directory; the step ran somewhere the file is not.

A misnamed or uncommitted bake file

The -f path is misspelled, or the bake file was never committed, so it is absent in CI.

How to fix it

Point bake at the real file path

1. Confirm the bake file exists and is committed.
2. Pass its path explicitly with -f, or set the step working directory.
3. Re-run bake from the directory that holds the file.

docker buildx bake -f docker-bake.hcl app

Set the working directory in the workflow

Run the bake step where the definition lives so the default lookup succeeds.

- run: docker buildx bake app
  working-directory: ./build

How to prevent it

• Commit the bake definition and reference it with an explicit -f.
• Set the step working directory to the file location.
• Validate docker buildx bake --print locally before pushing.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation