Docker "BuildKit is enabled but the buildx component is missing" in CI

By Kaveh Alemi·Latchkey

When DOCKER_BUILDKIT=1 is set, docker build delegates to the buildx CLI plugin. If that plugin binary is absent or unreadable, Docker reports that BuildKit is enabled but the buildx component is missing or broken, and the build cannot proceed.

What this error means

A docker build fails immediately with BuildKit is enabled but the buildx component is missing or broken, even though the daemon is healthy.

ERROR: BuildKit is enabled but the buildx component is missing or broken.
       Install the buildx component to build images with BuildKit:
       https://docs.docker.com/go/buildx/

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.

# 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

The buildx CLI plugin is not installed

A minimal Docker install or a custom CI image may ship the daemon and docker CLI but not the buildx plugin.

The plugin is in a directory Docker does not scan

A buildx binary placed outside ~/.docker/cli-plugins (or the system plugins dir) is not discovered.

How to fix it

Install the buildx plugin

1. On a GitHub Actions runner, set up buildx with the official action.
2. Or install the plugin binary into the cli-plugins directory.

- uses: docker/setup-buildx-action@v3
- run: docker buildx build -t myorg/app:ci .

Place the binary where Docker looks for plugins

1. Download the buildx release binary.
2. Install it as docker-buildx under the cli-plugins directory.

mkdir -p ~/.docker/cli-plugins
curl -fsSL -o ~/.docker/cli-plugins/docker-buildx \
  https://github.com/docker/buildx/releases/latest/download/buildx-linux-amd64
chmod +x ~/.docker/cli-plugins/docker-buildx
docker buildx version

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

• Use docker/setup-buildx-action in CI to guarantee the plugin is present.
• Bake buildx into custom runner images rather than relying on a minimal Docker install.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation