Fixing Buildx Builder Initialization Failures

DEV Community

setup-buildx-action failed to initialize builder is buildx speaking

setup-buildx-action failed to initialize builder is a sentence written by the buildx binary that the action shells out to, and it names a builder and a node rather than a cause. Everything diagnostic is in the third part of it, after the last colon, which is the error the driver returned when buildx tried to reach the node it had just registered. The format string is quoted from Create in buildx builder/builder.go. The log line is quoted from docker/docker-install#486. What this error means A docker/setup-buildx-action step fails in one of two named groups, Creating a new builder instance or Booting builder, and the log carries a line of the form failed to initialize builder (0): . The two identifiers are the builder group and the node inside it, and the node is simply the builder name with an index appended, so a doubled-looking suffix is expected rather than a corruption. The part worth reading is what follows the final colon: a daemon socket that cannot be reached, a request that timed out, or a driver that refused. The builder does not survive this, either, which changes what a retry means. ```Actions log, quoted from docker/docker-install#486, a run on docker/setup-buildx-action@v3 Creating a new builder instance Error: ERROR: failed to initialize builder builder-05f95600-d266-4d50-a4fd-39a423e5d0e0 (builder-05f95600-d266-4d50-a4fd-39a423e5d0e00): Cannot connect to the Docker daemon at unix:///run/user/1000/docker.sock. Is the docker daemon running?

Common causes

There is no reachable Docker daemon on the runner

The largest group by a distance, and the one the message names directly when it does. Self-hosted runners without Docker, container-based runners with no socket mounted, and GitHub-hosted macOS images all land here. The error after the colon names the socket or pipe that was tried, which is the fastest confirmation available.

The daemon is listening somewhere the client is not looking

Rootless installations put the socket under /run/user/<uid>, and a client configured for the system path finds nothing. The failure reads identically to having no daemon at all, so the endpoint in the message is the only thing that separates them.

The node was registered but BuildKit could not be started

This is the boot group rather than the create group. The docker-container driver has to pull and run a BuildKit image, so a registry that is unreachable, a rate limit, or a host with no room for another container stops it after registration succeeded.

The endpoint responded too slowly to be considered up

Buildx loads node data under a context, and a host that is reachable but very slow surfaces as a deadline rather than a refusal. In our experience this is mostly Docker Desktop and heavily loaded self-hosted machines, and it is the one case where a retry is a reasonable first move.

How to fix it

Read the endpoint out of the message before anything else

1. Find the text after the last colon on the failed to initialize builder line.
2. If it names a socket or pipe, compare that path with where your daemon actually listens.
3. If it names a deadline rather than a refusal, the host answered too slowly and the daemon is probably up.
4. Note which group failed, Creating a new builder instance or Booting builder, because they point in different directions.

Run buildx jobs where a daemon exists

On GitHub-hosted runners that means Linux. A macOS job cannot start a docker-container builder because those images ship no daemon, so a Docker build that has drifted onto a macOS runner has to move rather than be configured around.

```.github/workflows/docker.yml (illustrative)
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: docker/setup-buildx-action@v4
- uses: docker/build-push-action@v7
with:
push: false
Point the client at the socket the daemon is really on For rootless setups, set the Docker h...

Powered by Readybot.io