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.

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

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

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

- uses: docker/setup-buildx-action@v3
  with:
    driver: docker-container
    driver-opts: |
      image=moby/buildkit:latest

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

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions