Why the processor type matters
A container is not a virtual machine: it runs on the host's kernel, so the program inside has to be compiled for the host's processor. An image built for one architecture will not run on a host of another unless emulation sits in between. This catches teams whose developers use one kind of machine and whose servers use another, or whose CI runners differ from both. The build succeeds, the push succeeds, and only the first start on the server fails. The start-up message varies between systems, so do not rely on its exact wording; rely on the platform check below.
How a multi-platform image is built up
An image can be published as a manifest list, which is an index pointing to one image per platform. The registry stores the list and each member. When a host pulls the tag, Docker picks the member that matches the host. So the same tag can serve an arm machine and an x86 machine, provided somebody built and pushed both members. A tag that points to a single-platform image serves only that platform.
The inspection command for registry images shows the manifest and, for a list, one entry per platform. That is the quickest way to learn what a tag really contains, and it works without pulling the image.
Three ways to build for another platform
Emulation lets one machine build for another's architecture with no change to the Dockerfile, but it can be much slower than a native build, especially for compilation and compression. Native builders for each platform are faster and handle cases emulation cannot, at the cost of managing more than one builder. Cross-compilation builds the program on the builder's own platform for a different target, using the built-in build platform and target architecture arguments in a multi-stage Dockerfile; it is quick but only suits toolchains that can target other platforms.
Choose by the cost you can accept: build time, extra machines, or changes to the Dockerfile. If your pipeline runs only on one kind of machine and your server is another, emulation is the lowest-effort start.
- Emulation: no Dockerfile change, slower.
- Native builders: faster, more to manage.
- Cross-compilation: fast, needs toolchain support.
Checking before you trust it
Find the architecture of the laptop, the CI runner and the server. Inspect the registry entry for the tag the server pulls and confirm that it lists the server's platform. Start a container from the image on the target platform, or on an emulated one if that is all you have, and run the health check. Publish to a scratch tag during testing and never overwrite a tag that production uses.
How the paid outcome is accepted
Architecture is one possible cause covered by the fixed image-build job. It is accepted when the image builds from a fresh checkout for each agreed platform, the published manifest lists those platforms, a container passes the agreed health check and stays up, and the build arguments and image history we inspect show no secret value. It starts at £245, untested, and is paid after you sign off. Registry setup, billing and orchestration are excluded.
Sources and limits
- Docker multi-platform builds Checked 2026-10-11.
- Containers use the host kernel, so an image must match the host's CPU architecture unless emulation is involved; a multi-platform image is a manifest list pointing to one manifest per platform, and Docker pulls the variant that matches the host.
- Emulation with QEMU can be much slower than native builds; the alternatives are native nodes and cross-compilation using the BUILDPLATFORM and TARGETARCH arguments.
- docker buildx imagetools inspect Checked 2026-10-11.
- The command shows an image's manifest in the registry and, for a multi-platform image, lists each platform entry.