Docker buildx "no builder instance" in CI

By Kaveh Alemi·Latchkey

A buildx command needs an active builder, and none exists. On a fresh runner the buildx builder must be created (or the action that creates it must run) before building.

What this error means

A buildx build or bake fails with ERROR: no builder "..." found or no builder instance, typically right after invoking docker buildx on a clean runner.

ERROR: no builder "builder-abc" found
# or
ERROR: no builder instance is active, please create one with "docker buildx create"

Common causes

No builder created on the runner

A fresh runner has only the default builder (or none for advanced features), so a named/multi-platform build has nothing to run on.

Builder created in a different step/shell

A builder set up in one job or shell is not available in another that starts clean.

How to fix it

Create and use a builder

1. On Actions, use setup-buildx-action which creates and selects a builder.
2. Or create one manually before building.

- uses: docker/setup-buildx-action@v3

Bootstrap a builder by hand

1. Create a builder and make it current.

docker buildx create --name ci-builder --use --bootstrap

How to prevent it

• Add a buildx setup step before any buildx build in CI, so the builder always exists when the build runs.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation