docker/build-push-action "failed to solve" - Buildx not set up

By Daniel Zoghalchali·Latchkey

build-push-action drives a buildx builder. Without a prior docker/setup-buildx-action step there is no buildkit instance to solve the build graph, so the build fails.

What this error means

The build-push step fails with "failed to solve" or complains the buildx builder is missing.

github-actions

ERROR: failed to solve: failed to read dockerfile: buildx builder not initialized
##[error]buildx call failed with: ERROR: failed to solve

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

Missing setup-buildx step

No docker/setup-buildx-action ran, so build-push has no builder to use.

Builder failed to initialize

setup-buildx ran but the driver could not start, leaving no usable builder.

How to fix it

Add setup-buildx before build-push

Insert a docker/setup-buildx-action step before the build.
Optionally add setup-qemu for multi-arch.
Re-run; build-push uses the initialized builder.

.github/workflows/docker.yml

- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
  with:
    push: true
    tags: ghcr.io/${{ github.repository }}:latest

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

Always run setup-buildx-action before build-push-action.
Check the builder startup logs when the solve step fails immediately.

Frequently asked questions

What causes docker/build-push-action "failed to solve"?

There are 2 common causes: missing setup-buildx step and builder failed to initialize. No docker/setup-buildx-action ran, so build-push has no builder to use.

How do I fix docker/build-push-action "failed to solve"?

Add setup-buildx before build-push. Insert a docker/setup-buildx-action step before the build.

What does docker/build-push-action "failed to solve" actually mean?