A Docker container exits immediately with `exec format error` on an arm64 host but runs on amd64. How do you diagnose and fix it?

## Where the message comes from `exec format error` is the kernel's `ENOEXEC`, surfaced by the container runtime when it tries to `execve` your entrypoint. The kernel looked at the file, did not recognise it as something it can run, and refused. On containers there are two realistic causes, and separating them is the first move. **Cause one, the common one: wrong architecture.** The binary is a valid ELF executable, but built for a machine type this kernel cannot run — typically an `x86-64` image started on an `aarch64` host — and no `binfmt_misc` handler is registered to hand it to an emulator. **Cause two, the sneaky one: not an executable at all.** An exec-form `ENTRYPOINT ["/entrypoint.sh"]` runs the file directly, with no shell involved. If that script has no `#!` interpreter line, the kernel has nothing to interpret it with and returns exactly the same error, on any architecture. Worth ruling out early, because it looks identical in the logs. ## Diagnosing the architecture case Work outward from the container: ```bash # What did I actually pull? docker image inspect telemetry-gateway:4.2 --format '{{.Os}}/{{.Architecture}}' # What does the tag offer in the registry? docker buildx imagetools inspect registry.example.com/telemetry-gateway:4.2 # What is this host? uname -m docker version --format '{{.Server.Arch}}' ``` Three outcomes follow. If the tag offers only `linux/amd64` and the host is arm64, the image was never built for this hardware — the pull succeeded because a single-platform image is served to anyone who asks. If the tag offers both but the local image says `amd64`, someone pulled or ran with an explicit `--platform linux/amd64`, or an older cached image is being reused. If the image says `arm64` and it still fails, you are in cause two, or a cross-compiled binary was produced for the wrong architecture and copied into a correct-architecture base image — a classic mistake when a build stage is pinned to the build platform but the cross-compilation flags were never wired to `TARGETARCH`. A related error is worth distinguishing: if a tag offers several architectures but not the host's, the *pull itself* fails with a no-matching-manifest error. You never get as far as `exec format error`. Failing at pull means the tag knows about architectures and yours is not among them; failing at exec means an image did land locally and its contents are wrong for this kernel. ## The fixes, in order of preference 1. **Build the image for the architecture.** `docker buildx build --platform linux/amd64,linux/arm64 -t ... --push .` and the host pulls what it needs. This is the only fix that ends the problem. 2. **Run it emulated, deliberately.** `docker run --platform linux/amd64 telemetry-gateway:4.2` selects the amd64 variant. It works only where the host has emulation handlers registered in `binfmt_misc` — Docker Desktop sets those up for you, a plain Linux engine generally does not, which is why the same command works on a laptop and fails on a server. 3. **Run a different image.** For a sidecar or a debugging tool, the fastest fix is often an image that already publishes your architecture. ## The cost of choosing emulation Emulation is a correctness escape hatch, not a deployment strategy, and the numbers are brutal for anything CPU-bound. A telemetry ingest gateway run emulated on an arm64 host will show it everywhere: p99 ingest latency climbing from around 31 ms native to several hundred milliseconds, CPU per request several times higher, and JIT-compiled or heavily vectorised code punished worst of all because the emulator must translate the hot path instruction by instruction. The part teams miss is that emulation also stretches *timings that were tuned natively*. If the deployment stops the gateway with a 4-second SIGTERM grace period, chosen because a native flush of the in-memory batch takes well under a second, the emulated process can miss that window, take SIGKILL, and drop in-flight telemetry on every restart. The container is not crashing and the logs show a clean shutdown starting — it simply never finishes. The same class of problem hits health-check start periods, liveness timeouts and connection deadlines. When you knowingly run emulated, revisit every timeout that was calibrated on native hardware. ## Preventing the recurrence Make the tag multi-platform and verify it in CI with `docker buildx imagetools inspect`, so a silently single-architecture release is caught before deployment rather than by a container that will not start on the one arm64 node in the pool.