Multi-Platform Images, QEMU Emulation, Native Builders, Manifest Lists, and Cross-Architecture Delivery: Diagnostics, Failure Modes, Security, and Performance

1. Diagnostic rule: platform evidence before remediation

When a multi-platform build fails, preserve the build command, selected builder, buildx inspect, plain progress trace, requested platforms, Dockerfile frontend, source revision, and any index/manifest digests already produced. Do not start by deleting builder cache, changing daemon storage, installing emulators, or republishing tags. Those actions can erase the evidence that tells you which layer failed.

2. Evidence-first failure sequence

1. Confirm host/daemon/context and actual Engine/Buildx versions.
2. Confirm selected builder, driver, BuildKit version, nodes, and advertised platforms.
3. Confirm requested --platform set and automatic TARGET* values.
4. Find the first failing build vertex in plain progress.
5. Classify whether it required target-platform execution.
6. Inspect exporter/index state separately from local image-store state.
7. If published, resolve the exact index and child manifest digests.
8. Apply one bounded correction and rerun the smallest target/platform scope.

3. Failure mode: exec format error

An “exec format” error usually means a process binary does not match an executable platform available to the kernel/emulator path. It may occur during build or runtime. First compare the failing stage’s effective platform with the binary it is trying to execute. If the stage defaulted to the target platform, BuildKit may be trying to run arm64 user space on an amd64-only worker without emulation.

Do not fix this by blindly forcing the entire build to amd64; that can silently produce the wrong artifact. Decide whether the step should run on BUILDPLATFORM and cross-compile, or whether the builder legitimately needs arm64 execution through native/emulated capability.

4. Failure mode: the build “works” but arm64 compilation is extremely slow

Capture per-vertex timing from --progress=plain. If compile-heavy RUN steps execute in a target-platform stage on an amd64 workstation, QEMU is a likely performance cause. Compare with a build stage pinned to BUILDPLATFORM and a cross-compiling toolchain, or with a native arm64 node. Do not attribute every timing difference to QEMU; network downloads, cold caches, CPU limits, and different dependencies can also dominate.

5. Failure mode: using uname -m as the only target proof

uname -m reports what the executing kernel environment presents to the running process. In an emulated environment it can be useful runtime evidence; in a cross-compiling build stage it says nothing about the architecture of the artifact produced for another target. Pair runtime architecture with TARGETARCH, binary-format inspection, OCI platform descriptor, and target tests.

6. Failure mode: expecting every multi-platform output to appear in the local image list

Build output is exporter-specific. A docker-container builder does not automatically place results in the Engine image store. OCI output creates a file/layout. Registry output pushes content. Local loading depends on exporter choice and whether the image store supports the result. Fresh Engine 29 and Docker Desktop containerd stores support multi-platform images, but upgraded/classic stores can differ.

Evidence chain: inspect the build command → identify exporter → inspect its destination → only then ask what local image state should exist. “Build succeeded but docker image ls shows nothing” can be correct behavior.

7. Failure mode: index exists, one variant is broken

A top-level index can be structurally valid while one platform image is unusable. Resolve every descriptor and maintain separate test evidence. If arm64 fails, record the arm64 manifest digest and test result; do not republish the same tag after rebuilding one child without capturing the new top-level index digest. Any child descriptor change changes the index content and therefore its digest.

8. Failure mode: the wrong builder is selected

Buildx supports multiple builders with different drivers, workers, caches, and platform capabilities. A workstation can switch builders implicitly through previous commands. Always record docker buildx ls and explicitly pass --builder in reproducible automation. If a build suddenly loses arm64 support, confirm builder selection before changing emulators or Dockerfiles.

9. Security-sensitive remediation boundaries

Host-level emulator registration, remote builder administration, daemon image-store migration, and registry publication can be disruptive or privileged. Keep them out of first-line troubleshooting. Use an authorized disposable VM or managed Desktop environment when experimentation requires those capabilities. Remote native builder nodes should use narrow credentials and should not accept untrusted build input with release secrets.

Never turn a platform problem into a broad isolation exception. The fact that a build cannot execute a foreign binary is not evidence that seccomp, firewall, TLS, or other host protections should be weakened.

10. Intentionally broken example: target-stage execution without capability

# syntax=docker/dockerfile:1
FROM alpine:3.22 AS build
ARG TARGETARCH
RUN echo "target=$TARGETARCH" > /target.txt
FROM scratch
COPY --from=build /target.txt /target.txt

With --platform linux/amd64,linux/arm64, the build stage defaults to each target platform. The RUN therefore requires target-platform execution. On a builder without arm64 native/emulation support, arm64 can fail even though the step merely echoes text.

The bounded correction is:

FROM --platform=$BUILDPLATFORM alpine:3.22 AS build
ARG BUILDPLATFORM
ARG TARGETPLATFORM
ARG TARGETARCH
RUN printf 'build=%s target=%s arch=%s\n' \
    "$BUILDPLATFORM" "$TARGETPLATFORM" "$TARGETARCH" > /target.txt

Now the RUN executes on the build platform while producing target-labeled data. This is not a universal fix: if the final artifact genuinely requires target binaries or target-specific package-manager scripts, choose a suitable native/emulated/cross-compilation strategy instead.

11. Performance diagnosis without sacrificing correctness

Measure build duration per platform, per expensive vertex, cache hit rate, network transfer, and CPU utilization. Compare strategy changes with the same source, dependency state, builder resources, and cache conditions. A faster build that skips target tests or emits the wrong architecture is not an optimization.

12. Recovery and smallest safe rerun

If only arm64 failed, rerun only arm64 while diagnosing. Preserve the successful amd64 digest and logs. After the fix, run the full two-platform build to produce a new coherent index and then rerun per-platform verification. This separates local diagnosis from final release creation.

Knowledge check

Official references and version notes

• Docker multi-platform builds — current prerequisites, QEMU, multiple native nodes, cross-compilation, automatic platform arguments, and local image-store guidance.
• containerd image store with Docker Engine — Engine 29 fresh-install default, multi-platform local storage, snapshotters, upgrade caveats, and userns-remap limitation.
• Docker Desktop containerd image store — Desktop image-store behavior and multi-platform/attestation support.
• docker buildx build — --platform, exporters, metadata, progress, builder selection, and output semantics.
• docker buildx inspect — builder driver, BuildKit nodes, status, and platform capability evidence.
• Automatic platform ARGs — BUILDPLATFORM, TARGETPLATFORM, TARGETOS, TARGETARCH, and stage-scope behavior.
• OCI Image Index Specification — higher-level descriptors and platform selection.
• OCI Image Manifest Specification — per-platform config and layer descriptors.
• OCI Descriptor Specification — digest, size, media type, and platform metadata.
• Docker Engine 29 release notes — current Engine baseline and multi-platform image load/save updates.
• Buildx releases — current Buildx release history.
• BuildKit releases — current BuildKit and Dockerfile frontend history.