GitHub Actions setup-buildx "driver-opts invalid"

By Kaveh Alemi·Latchkey

setup-buildx-action validates driver and driver-opts. Passing an option that the selected driver does not support, or malformed key=value pairs, fails builder initialization. This is a configuration error.

What this error means

The setup-buildx step fails creating the builder, complaining about an unrecognized or malformed driver option.

github-actions

Error: failed to initialize builder: invalid driver-opts: "image=moby/buildkit:latest,network"
unknown driver-opt for driver "docker"

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

Option not valid for the chosen driver

A driver-opt like network or image is set on a driver that does not accept it (e.g. the default docker driver).

Malformed key=value list

driver-opts is not formatted as comma- or newline-separated key=value entries.

How to fix it

Use valid options for the driver

Select the docker-container driver when you need image/network driver-opts.
Format driver-opts as key=value entries.
Remove options not supported by the chosen driver.

.github/workflows/build.yml

- uses: docker/setup-buildx-action@v3
  with:
    driver: docker-container
    driver-opts: |
      image=moby/buildkit: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

Match driver-opts to the capabilities of the selected buildx driver.
Keep driver-opts as clean key=value entries.

Frequently asked questions

What causes GitHub Actions setup-buildx "driver-opts invalid"?

There are 2 common causes: option not valid for the chosen driver and malformed key=value list. A driver-opt like network or image is set on a driver that does not accept it (e.g.

How do I fix GitHub Actions setup-buildx "driver-opts invalid"?

Use valid options for the driver. Select the docker-container driver when you need image/network driver-opts.

What does GitHub Actions setup-buildx "driver-opts invalid" actually mean?