GitHub Actions docker/setup-buildx-action Fails to Create the Builder

By Kaveh Alemi·Latchkey

docker/setup-buildx-action could not create or boot the builder. Cross-arch builds need QEMU set up first, and the docker-container driver pulls a buildkit image that can fail to download transiently.

What this error means

The buildx setup step fails to create or bootstrap the builder, or a later multi-arch build fails with an exec format error because QEMU was never installed.

ERROR: failed to initialize builder: failed to bootstrap builder:
failed to pull moby/buildkit:buildx-stable-1 (transient)

Common causes

Missing QEMU for cross-arch builds

Building for a non-native platform needs docker/setup-qemu-action before buildx, or the emulated build fails with an exec format error.

Transient buildkit image pull

The docker-container driver pulls a buildkit image to bootstrap. A brief registry blip fails the bootstrap even when the configuration is correct.

How to fix it

Set up QEMU then buildx

- uses: docker/setup-qemu-action@v3
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64

Retry transient bootstrap failures

1. Add setup-qemu-action before buildx for any non-native platform.
2. Re-run when the bootstrap fails pulling the buildkit image.
3. Keep the buildx and build-push actions on compatible majors.

How to prevent it

• Install QEMU before buildx for multi-arch builds.
• Retry transient buildkit-image pulls.
• Keep the Docker setup/build actions on matching majors.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions