buildx "Cache export is not supported for the docker driver" in CI

By Daniel Zoghalchali·Latchkey

The default docker driver only supports the inline cache backend. Exporting to --cache-to type=gha, type=registry, or type=local requires the docker-container driver, so buildx refuses the export and suggests switching drivers.

What this error means

A build with --cache-to fails with "ERROR: Cache export is not supported for the docker driver. Switch to a different driver, or turn on the containerd image store, and try again."

ERROR: Cache export is not supported for the docker driver.
Switch to a different driver, or turn on the containerd image store, and try again.
Learn more at https://docs.docker.com/go/build-cache-backends/

Common causes

Building with the default docker driver

No docker-container builder was created, so buildx uses the bundled docker driver, which cannot export cache to gha, registry, or local.

The containerd image store is off

Without the containerd snapshotter, the docker driver lacks the cache export capability the backend needs.

How to fix it

Create a docker-container builder

1. Add the setup-buildx action so a docker-container builder is created.
2. Run the build through that builder.
3. Keep --cache-to/--cache-from unchanged; the export now works.

- uses: docker/setup-buildx-action@v3
  with:
    driver: docker-container

Or enable the containerd image store

On a self-managed daemon, turn on the containerd snapshotter so the docker driver gains cache export.

{
  "features": { "containerd-snapshotter": true }
}

How to prevent it

• Always set up a docker-container builder before using cache backends.
• Keep the setup-buildx step ahead of build-push steps.
• Reserve the inline cache backend for the plain docker driver.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation