buildx "failed to solve: the Dockerfile cannot be empty" in CI

By Daniel Zoghalchali·Latchkey

BuildKit read the Dockerfile it was given and found no instructions in it. The file exists but is empty or contains only blank lines and comments, so there is nothing to build.

What this error means

A build fails immediately with "ERROR: failed to solve: the Dockerfile cannot be empty" even though a Dockerfile path is present.

buildx

ERROR: failed to solve: the Dockerfile cannot be empty

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

An empty or comment-only Dockerfile

The file has no FROM or other instruction, possibly a placeholder that was never filled in or truncated by a bad checkout.

A generated Dockerfile that produced no content

A templating or heredoc step that should write the Dockerfile emitted an empty file, so BuildKit gets nothing.

How to fix it

Confirm the Dockerfile has instructions

Check the file size and first lines of the Dockerfile in CI.
Ensure it starts with a FROM instruction.
If it is generated, verify the generating step actually wrote content.

Dockerfile

FROM python:3.12-slim
COPY . /app
WORKDIR /app

Point -f at the correct file

If the real Dockerfile lives elsewhere, pass its path so BuildKit reads the right one.

Terminal

docker buildx build -f docker/Dockerfile .

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

Commit a non-empty Dockerfile with at least a FROM line.
Validate generated Dockerfiles are written before building.
Reference the intended Dockerfile path with -f.

Frequently asked questions

What causes buildx "failed to solve: the dockerfile cannot be empty" in CI?

There are 2 common causes: an empty or comment-only dockerfile and a generated dockerfile that produced no content. The file has no FROM or other instruction, possibly a placeholder that was never filled in or truncated by a bad checkout.

How do I fix buildx "failed to solve: the dockerfile cannot be empty" in CI?

There are 2 fixes depending on which cause you have: confirm the dockerfile has instructions and point -f at the correct file. Work through them in order, since the first is the most common.

What does buildx "failed to solve: the dockerfile cannot be empty" in CI actually mean?