Docker "--platform linux/arm64 not supported" - Fix Missing Emulation

You requested a non-native --platform, but the runner has no emulation registered to run that architecture’s binaries. Without QEMU/binfmt, the platform simply is not available.

What this error means

A build or run with --platform linux/arm64 on an amd64 runner fails with a "platform not supported" or "exec format" style error during a RUN step. The same Dockerfile builds natively on an arm64 host.

docker build output

ERROR: failed to solve: failed to load LLB: ... --platform linux/arm64 not supported
# or a RUN step inside the foreign-arch stage failing with exec format error

Common causes

No QEMU/binfmt registered for the target arch

Emulating a foreign architecture needs binfmt_misc handlers installed. On a bare runner they are absent, so any RUN in the foreign-arch stage cannot execute.

The default docker driver can’t emulate

Even with QEMU available, the default builder driver limits cross-platform builds; the container driver plus binfmt is the supported path.

How to fix it

Register QEMU/binfmt before building

Install the emulation handlers so the runner can execute foreign-arch binaries.

Terminal / Actions

docker run --privileged --rm tonistiigi/binfmt --install all
# in GitHub Actions:
- uses: docker/setup-qemu-action@v3

Use a container-driver builder with platforms

Combine QEMU with a docker-container builder for cross-arch builds.

Terminal

docker buildx create --driver docker-container --use
docker buildx build --platform linux/arm64 -t myorg/api:1.4.2 .

How to prevent it

Register QEMU/binfmt as a setup step in any cross-arch workflow.
Use the docker-container driver for emulated builds.
Prefer native-arch runners for performance-sensitive foreign-arch builds.