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.

github-actions

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

Diagnose it: is the job queued, or is the runner gone?

A job that never starts and a job whose runner disappeared mid-run look similar in the UI and have opposite causes. The first is a labelling or capacity problem, the second is the runner being killed, usually by memory pressure or a spot reclaim.

.github/workflows/ci.yml

- name: Runner facts
  run: |
    echo "runner name: $RUNNER_NAME"
    echo "os/arch:     $RUNNER_OS/$RUNNER_ARCH"
    nproc; free -h; df -h /
    echo "labels this job asked for: ${{ toJSON(job) }}"

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

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

.github/workflows/ci.yml

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

The failures that are not your workflow

Exit 137 is the kernel out-of-memory killer, not an application error. Check free -h above against your peak usage.
Disk exhaustion presents as unrelated write errors deep in a build. GitHub-hosted runners ship roughly 14 GB of free space, which a Docker-heavy job can exhaust.
A lost connection to the server on a self-hosted runner is usually the host being reclaimed or rebooted, not a network fault in your job.
A job that starts and immediately fails with no step output normally failed during runner setup, before your workflow ran at all.

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

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

There are 2 common causes: no docker daemon on the runner and cross-platform build without qemu. macOS and some self-hosted runners have no Docker daemon, so the docker-container driver cannot start.

How do I fix GitHub Actions docker/setup-buildx-action "failed to initialize builder"?

Provide a working Docker host and QEMU. Run buildx jobs on a Linux runner with Docker available.

What does GitHub Actions docker/setup-buildx-action "failed to initialize builder" actually mean?