Docker "the --mount option requires BuildKit" - Enable BuildKit in CI

By Kaveh Alemi·Latchkey

Your Dockerfile uses BuildKit-only syntax (RUN --mount=...) but the build ran with the legacy builder, which does not understand it.

What this error means

The build fails on the first RUN --mount=... line with the --mount option requires BuildKit. The same Dockerfile builds fine on a machine where BuildKit is the default.

docker build output

the --mount option requires BuildKit. Refer to https://docs.docker.com/go/buildkit/
to learn how to build images with BuildKit enabled.

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

BuildKit is disabled on this runner

Older Docker, or an environment with DOCKER_BUILDKIT=0, falls back to the legacy builder. Cache/secret/ssh mounts are BuildKit features and are rejected.

Building through a path that bypasses BuildKit

Some tools or wrappers invoke the legacy build API even on a host that could use BuildKit, so the mount syntax is not recognized.

How to fix it

Enable BuildKit explicitly

Turn BuildKit on via the environment variable for the build.

Terminal

DOCKER_BUILDKIT=1 docker build .
# or set it for the whole job
export DOCKER_BUILDKIT=1

Use buildx for consistent BuildKit behavior

In GitHub Actions, set up buildx so BuildKit is always the builder.

.github/workflows/build.yml

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    context: .
    push: false

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

Set DOCKER_BUILDKIT=1 (or use buildx) in any pipeline using mount syntax.
Pin a Docker version where BuildKit is the default.
Document the BuildKit requirement next to the Dockerfile.

Frequently asked questions

What causes Docker "the --mount option requires BuildKit"?

There are 2 common causes: buildkit is disabled on this runner and building through a path that bypasses buildkit. Older Docker, or an environment with DOCKER_BUILDKIT=0, falls back to the legacy builder.

How do I fix Docker "the --mount option requires BuildKit"?

There are 2 fixes depending on which cause you have: enable buildkit explicitly and use buildx for consistent buildkit behavior. Work through them in order, since the first is the most common.

What does Docker "the --mount option requires BuildKit" actually mean?

The build fails on the first RUN --mount=...

How do I stop Docker "the --mount option requires BuildKit" happening again?

Set DOCKER_BUILDKIT=1 (or use buildx) in any pipeline using mount syntax. The prevention section lists 3 changes that keep it from recurring.