GitHub Actions docker/setup-buildx-action "failed to initialize builder"

By Daniel Zoghalchali·Latchkey

docker/setup-buildx-action creates a buildx builder backed by a driver (docker-container by default). A missing Docker daemon, an unavailable driver, or absent QEMU for cross-platform builds stops the builder from coming up.

What this error means

A setup-buildx-action step fails creating or bootstrapping the builder, sometimes referencing the docker-container driver or a platform that needs emulation.

ERROR: failed to initialize builder builder-xxxx (builder-xxxx0):
error during connect: Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Common causes

No Docker daemon on the runner

macOS and some self-hosted runners have no Docker daemon, so the docker-container driver cannot start.

Cross-platform build without QEMU

Building for non-native platforms needs docker/setup-qemu-action first; without it the builder cannot emulate.

How to fix it

Provide a working Docker host and QEMU

1. Run buildx jobs on a Linux runner with Docker available.
2. Add docker/setup-qemu-action before setup-buildx for multi-arch builds.
3. Keep setup-buildx-action and build-push-action versions current.

- uses: docker/setup-qemu-action@v3
- uses: docker/setup-buildx-action@v3

How to prevent it

• Run Docker builds on Linux runners that have a daemon.
• Add QEMU setup whenever you target non-native platforms.
• Latchkey managed runners ship a ready Docker daemon and warm buildx, and auto-retry transient builder bootstrap failures.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions