exec format error in Docker: the image was built for another CPU
The kernel refused to run the container's program because it is not an executable for this machine: almost always a binary or image built for arm64 (an Apple Silicon Mac) running on an amd64 server, or the reverse. Build for the server's platform with --platform linux/amd64, or as a multi-platform image; if the file is a script, give it a #! line.
By Livops team, the people who build and run LivopsUpdated
The line in the container’s log, in its two common forms:
exec /usr/local/bin/docker-entrypoint.sh: exec format error
standard_init_linux.go:228: exec user process caused: exec format error
This page explains what the kernel is refusing, lists the causes from the most common, shows how to check an image and a binary before you deploy, and says what Livops does with a Dockerfile.
What does the error mean?
When a container starts, the kernel is asked to execute the image’s entrypoint. If the file is not an executable it can run — a program compiled for another processor, or a text file it cannot recognise as a script — it refuses with exec format error. Nothing of your code has run yet, so the app prints nothing else.
By default an image is built for the platform of the build request, that is, the machine you build on[2]. Build on an arm64 laptop, run on an amd64 server, and you get this error.
Causes, most common first
1. The image was built on an Apple Silicon Mac
The image is linux/arm64 and the server is linux/amd64. Build for the server, or for both[1]:
docker buildx build --platform linux/amd64 -t myapp .
docker buildx build --platform linux/amd64,linux/arm64 -t myapp --push .
Building for another platform on your machine runs under QEMU emulation, which Docker Desktop supports out of the box, and can be much slower than a native build[1].
2. FROM pins another platform
FROM --platform=linux/arm64 node:22, or an architecture-specific image such as arm64v8/node. The --platform flag on FROM chooses a variant of a multi-platform image[2]; remove it, or use the image’s normal multi-platform name.
3. A binary built for the wrong architecture is copied in
A Go or Rust binary built on your Mac and committed, or a release asset downloaded for arm64 in a RUN curl line. Build it inside the Dockerfile for the target platform. BUILDPLATFORM and TARGETARCH are filled in automatically, and --platform=$BUILDPLATFORM lets a stage run natively and cross-compile for the target[2]:
FROM --platform=$BUILDPLATFORM golang:1.25 AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/server .
FROM gcr.io/distroless/static-debian12
COPY --from=build /out/server /server
ENTRYPOINT ["/server"]
For downloads, pick the asset with TARGETARCH instead of hard-coding arm64 or amd64. These platform arguments are global: declare them with ARG inside the stage that uses them[2].
4. The entrypoint is a script without a #! line
The exec form of ENTRYPOINT and CMD does not start a shell[2], so the kernel executes the file directly and needs its first line to say which interpreter runs it:
#!/bin/sh
set -e
exec "$@"
If the script has Windows line endings, the first line becomes #!/bin/sh\r, and the error changes to no such file or directory for a file that plainly exists. Save it with LF endings.
5. The file is not the program at all
A zero-byte file from a failed download, or a Git LFS pointer — a small text file — committed instead of the binary. Both are rejected the same way. Check the file’s size and first bytes.
How to confirm the fix locally
Check the image and the file before you push:
docker image inspect myapp | grep -E '"(Architecture|Os)"'
file ./server # ELF 64-bit ... x86-64, or ... ARM aarch64
head -c 64 docker-entrypoint.sh | od -c | head -3 # shows #! and any \r
Then run the platform the server runs. --platform on docker run chooses the variant when the daemon is multi-platform capable[3], and docker image inspect --platform inspects one variant of a multi-platform image[4]:
docker run --rm --platform linux/amd64 myapp
If the amd64 variant starts on your machine, it starts on an amd64 server.
On Livops
- Livops builds your Dockerfile itself. When the project has a
Dockerfile, Livops builds it on its own servers, so cause 1 (an image built on your laptop) does not come up. - Causes 2 to 5 still apply. A
FROMpinned toarm64, an arm64 binary committed to the repository or downloaded in aRUNline, or a script without#!fails here the same way. - A ready-made image needs a variant for the server. A public image you run as a service is pulled as it is published; if it lacks a variant for the server’s CPU, it stops with this error. A multi-platform image avoids this.
- What you see. The app does not start, the deploy fails as
start_failed, its log carries the container’s last line — this error. A web app’s previous version keeps running; a bot’s was stopped before the new one started. - No dedicated Tip for this error. Livops has no Tip line written for
exec format error. The assistant’s button next to the failed deploy reads the log and explains it; it does not change your Dockerfile.
More on failed starts and Dockerfiles: The app did not start and The Dockerfile’s image no longer exists.
Questions
Why does the image run on my Mac and not on the server?
An Apple Silicon Mac builds arm64 images by default, and Docker Desktop can also run amd64 ones under emulation, so both work for you. A typical Linux server is amd64 and runs only amd64 binaries.
How do I see which architecture an image is?
Run docker image inspect on it and look at the Architecture field, for example docker image inspect myapp | grep Architecture. For a binary, the file command says x86-64 or aarch64.
Is exec format error ever not about the architecture?
Yes. A shell script started without a #! first line, an empty file, or a Git LFS pointer committed instead of the real binary give the same error. Check the first bytes of the file.
Should I always build multi-platform images?
If the same image runs on Macs and on amd64 servers, yes: docker buildx build --platform linux/amd64,linux/arm64 builds both, and each machine pulls its own. Otherwise build for the server's platform only.
Do I need --platform on Livops?
Not for the build itself: Livops builds your Dockerfile on its own servers, for the machine it runs on. What you still control is anything the Dockerfile downloads or copies in ready-made: pick it with TARGETARCH so it matches the build.
Sources
- Docker docs — Multi-platform builds (docs.docker.com). Checked .
- Docker docs — Dockerfile reference (FROM --platform, platform ARGs, exec form) (docs.docker.com). Checked .
- Docker docs — docker container run (docs.docker.com). Checked .
- Docker docs — docker image inspect (docs.docker.com). Checked .
Put your project online today
Connect GitHub or drop a folder. No card is asked for.
Deploy your DockerfileRelated
- App not listening on $PORT: why the health check failed after deployThe platform started your app, tried the port it gave it, and nothing answered in time. Almost always the app listens on its own fixed port instead of the PORT variable, listens on localhost (127.0.0.1) instead of 0.0.0.0, or crashed or was still starting when the check gave up. Listen on 0.0.0.0 and the port in PORT, and it passes.
- Error: listen EADDRINUSE: address already in use — how to fix itYour server tried to listen on a port that another process on the same machine already holds. On your computer, stop the old process, usually a dev server still running in another terminal. In a deploy, it almost always means the app starts its server twice, or two processes in one container ask for the same port.
- npm ERR! code 1: why the build failed with exit code 1npm ERR! code 1 (npm error code 1 in newer npm) only says that a script npm ran exited with code 1. The real error is printed above it: usually a compile or type error, a lockfile out of sync with package.json, or a dependency whose install script failed. Find the first error line above code 1, fix that, and the build passes.