Versions: Docker Engine 29.10, Buildx 0.39, Go 1.27 (golang:1.27-alpine), nginx:1.29-alpine
Your image works on your laptop. You push it, the server pulls it, and the container dies straight away with exec format error. In Docker, this error almost always means the image was built for a different CPU than the server it runs on: usually an ARM image from an Apple Silicon Mac landing on an x86 (amd64) server. This guide shows you how to prove that in one command, how to fix it for good, and the less obvious cases where an image that says amd64 still carries an ARM binary.
What "exec format error" means
When a container starts, Docker asks the Linux kernel to run its entrypoint. The kernel looks at the first bytes of the file. If it's a program for another CPU, or a script with no #! line, the kernel refuses with ENOEXEC, which prints as "exec format error".
Here's what the kernel returns for four common files on an x86 machine:
| File | Error |
|---|---|
| A program compiled for ARM64 | exec format error |
A shell script with no #!/bin/sh first line | exec format error |
A script whose first line has a space before #! | exec format error |
A script saved with Windows line endings (#!/bin/sh\r) | no such file or directory |
So two different problems give the same message. The CPU mismatch is far more common, so check it first. Windows line endings give a different error, which is useful when you're narrowing things down.
Step 1: Confirm it's the CPU
First, find out what the server runs. On the server (or in any container on it):
uname -m x86_64 means amd64. aarch64 means arm64. Most hosting platforms, Hubfly space included, run x86_64, though ARM cloud servers are increasingly common.
Then check the image. This works for an image you have locally:
docker image inspect --format '{{.Os}}/{{.Architecture}}' shop-api:latest If it prints linux/arm64 and the server is x86_64, you've found the problem.
On a single-platform image, that's the whole story. On a multi-platform image it isn't. docker image inspect shows only the variant for your machine, so a laptop can report linux/amd64 for an image that has both. To see every variant inside an image, use:
docker image ls --tree shop-api IMAGE ID DISK USAGE CONTENT SIZE EXTRA shop-api:multi 8bf093d62c1d 7.04MB 2.63MB ├─ linux/amd64 dcfdddb4009f 3.57MB 1.35MB └─ linux/arm64 8fe2bc9092ed 3.47MB 1.28MB For an image that's already in a registry, ask the registry instead of your laptop:
docker buildx imagetools inspect your-registry/shop-api:latest A multi-platform image lists a Manifests: section with one Platform: line per variant (linux/amd64, linux/arm64, plus unknown/unknown entries, which are build attestations, not images). A single-platform image shows one manifest and no list. If linux/amd64 isn't in that list, an x86 server can't run the image.
You can also reproduce the error on purpose. On an x86 machine, an ARM-only image fails like this:
$ docker run --rm shop-api:arm64 WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64/v4) and no specific platform was requested exec /app: exec format error The exit code is 255. That warning line is the giveaway, but most hosting platforms don't show it to you. You only see the last line.
Step 2: Build for the server's CPU
The quickest fix is to build the image for the platform the server runs. With Docker's default builder (BuildKit), add --platform:
docker buildx build --platform linux/amd64 -t your-registry/shop-api:latest --push . Docker Desktop on a Mac runs this through emulation, so it works without changing the Dockerfile. It's slower than a native build, because every RUN step runs through an emulator.
If the image should run on both kinds of machines (your M-series laptop and an x86 server), build both variants into one tag:
docker buildx build --platform linux/amd64,linux/arm64 -t your-registry/shop-api:latest --push . The registry stores both and each machine pulls the one it can run. Check the result with docker buildx imagetools inspect from Step 1.
Step 3: Cross-compile instead of emulating
For compiled languages such as Go and Rust, emulation is the slow way. The compiler can produce a binary for another CPU while running natively. Docker passes you the information you need as build arguments: BUILDPLATFORM (the machine doing the build) and TARGETOS / TARGETARCH (the platform you asked for).
Here is a two-stage Dockerfile for a Go service that does it properly:
FROM --platform=$BUILDPLATFORM golang:1.27-alpine AS build ARG BUILDPLATFORM ARG TARGETPLATFORM ARG TARGETOS ARG TARGETARCH WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . RUN echo "building on $BUILDPLATFORM for $TARGETPLATFORM" && \ CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/server . FROM gcr.io/distroless/static-debian13 COPY --from=build /out/server /server ENTRYPOINT ["/server"] Why each piece is there:
-
FROM --platform=$BUILDPLATFORMruns the build stage on your own CPU, so the Go compiler runs at full speed. -
GOOS=$TARGETOS GOARCH=$TARGETARCHtells the compiler which CPU the binary is for. - The
echoline prints both platforms in the build log, so you can see what the builder actually passed in. - The final stage has no
--platform, so Docker uses the target platform for it and labels the image correctly.
The half-done version that ships the wrong binary
Plenty of Dockerfiles have the first line but not the second: FROM --platform=$BUILDPLATFORM and then a plain go build. That is worse than having neither. The build stage runs on your laptop's CPU, Go compiles for your laptop's CPU, and Docker still labels the result with the platform you asked for.
Build both on an x86 machine with --platform linux/amd64,linux/arm64 and here's which binary lands in each variant:
| Dockerfile | Binary in the amd64 variant | Binary in the arm64 variant |
|---|---|---|
GOARCH=$TARGETARCH set | x86-64 | ARM aarch64 |
GOARCH not set | x86-64 | x86-64 |
On an Apple Silicon laptop the same mistake works the other way: the linux/amd64 variant holds an ARM binary. imagetools inspect says linux/amd64 is there, the server pulls it, and the container still fails with exec format error. If your registry says the right platform exists and you still get the error, look for this.
Don't give the platform arguments default values
It's tempting to write ARG TARGETARCH=amd64 "just in case". Don't. A default you set wins over the value Docker fills in, so every variant gets the same binary. With ARG TARGETARCH=amd64, the arm64 variant ends up with an x86-64 binary too. Declare them with no value, as in the Dockerfile above. If the arguments arrive empty, GOARCH= is empty too and Go builds for the CPU it's running on, which is what you want on a builder that doesn't set them.
Step 4: Let the server build it
The other way out is to stop building images on your laptop at all. Push your code to Git and let the platform build it on the same kind of machine it runs on. Then the image matches the server by default.
On Hubfly space:
- In the dashboard, click Create project, give it a name, pick a region and click Create project.
- Click Create → Create Container, name it (for example
shop-api) and choose Git repository. - Connect your repository with the GitHub App, or choose Self-hosted Git and paste any public HTTPS URL. Set the Branch, and the Repository directory if the app lives in a subfolder.
- A
Dockerfileat the top of that folder is used automatically. To use a different one without committing it, untick Automatically detect the build and paste it into Custom Dockerfile. The form then also asks for a run command; enter your binary's path (/serverhere). The Dockerfile'sENTRYPOINTis what actually runs. - On Resources, pick a tier, then go to Review and click Start Build.
A two-stage Go service like this builds in about a minute. To reach it, open the container, go to Network, click Add Domain, keep Auto Endpoint, check that Container port is the port your app listens on (80 for this example), and click Create Subdomain. You get an HTTPS address ending in .hubfly.app. If the very first build stops with a network error before your Dockerfile steps run, click Edit & retry and start it again.
Two things in that log are worth knowing:
- The builder doesn't fill in the platform arguments. The line
building on $BUILDPLATFORM for $TARGETPLATFORMprinted asbuilding on for. Because the Dockerfile declares them with no default,GOARCHis empty and Go builds for the builder's own CPU, which is x86-64. This is why the "no defaults" rule above matters. - A hard-coded
--platform=linux/arm64doesn't trip it up. A Dockerfile withFROM --platform=linux/arm64 golang:1.27-alpineand a plaingo buildstill builds an x86-64 image (about 40 seconds) and runs. Don't rely on that elsewhere: remove hard-coded platforms from yourFROMlines.
An always-on Dedicated container with 0.5 vCPU, 512 MB of RAM and 4 GB of disk costs about $2.23 a month (0.5 × $0.004 × 730 h for CPU = $1.46, 0.5 GB × $0.002 × 730 h for RAM = $0.73, 4 GB × $0.00001536 × 730 h for disk = $0.04). Builds are free. Creating resources needs a one-time $5 deposit, which stays in your account as credit.
What can go wrong
The deploy fails with a generic message and no logs. If the tag points to a multi-platform list that has no linux/amd64 entry (for example arm64v8/nginx:1.29-alpine), the server can't pick a variant at all. On Hubfly space this shows as Deployment Failed with "The container could not be started. Check the image and configuration, then deploy again." after about three minutes, and the Logs tab only says "Runtime not found in this region". The message doesn't name the cause, so run docker buildx imagetools inspect on the tag and look for linux/amd64.
The container shows Running, then restarts every second or two. When the server is handed an ARM image directly (for example by digest, image@sha256:…), it pulls it, starts it, and the kernel refuses it. The status flips between Running and Deploying, and the log fills with the same line:
Rebuild for linux/amd64 (Step 2) or let the platform build it (Step 4). Restarting won't help.
exec /docker-entrypoint.sh: exec format error, but the image is amd64. Check the script. If its first line isn't #!/bin/sh (or #!/bin/bash), or there's a space or a blank line before #!, the kernel can't tell what should run it. A script with no #! line fails like this: exec /start.sh: exec format error.
no such file or directory for a script that's clearly there. That's usually Windows line endings: the kernel looks for an interpreter called /bin/sh\r. Convert the file with dos2unix, or add a .gitattributes line such as *.sh text eol=lf so Git checks it out with Unix endings.
failed to parse platform : "" is an invalid OS component. You built with the old builder (DOCKER_BUILDKIT=0), which doesn't set BUILDPLATFORM. Use docker buildx build, or the default docker build on a current Docker Engine, which uses BuildKit.
Multi-platform build is not supported for the docker driver. Your Docker setup stores images the old way. Turn on the containerd image store in Docker Desktop's settings, or create a separate builder with docker buildx create --use --driver docker-container. On a Linux CI runner, install the emulators and a buildx builder first (on GitHub Actions, docker/setup-qemu-action then docker/setup-buildx-action).
The amd64 build is very slow on a Mac. Emulated RUN steps (compiling native modules, apt-get install) are much slower than native ones. Cross-compile as in Step 3 where your language allows it, or let a server build the image (Step 4).
FAQ
What does "exec format error" mean in Docker?
The kernel refused to run the container's entrypoint. In most cases the image was built for another CPU, such as an arm64 image on an amd64 server. Less often, the entrypoint is a script with no #! line.
How do I check which architecture a Docker image is?
Run docker image inspect --format '{{.Os}}/{{.Architecture}}' image for a local image, docker image ls --tree image to see every variant, and docker buildx imagetools inspect image for an image in a registry.
Why does docker image inspect show amd64 when the image is ARM?
For a multi-platform image it shows the variant for your own machine, not the whole image. Use docker image ls --tree or docker buildx imagetools inspect to see all variants.
How do I build an amd64 image on an Apple Silicon Mac?
Run docker buildx build --platform linux/amd64 -t your-image --push .. For Go or Rust, add FROM --platform=$BUILDPLATFORM to the build stage and pass TARGETOS/TARGETARCH to the compiler, so the build doesn't have to run under emulation.
Can an amd64 server run an arm64 image?
Only if the server has an emulator (QEMU through binfmt) installed. Hubfly space runs images natively on x86-64, so publish an amd64 variant instead.
Why does my entrypoint script give exec format error?
Its first line isn't a valid #! line. Add #!/bin/sh as the very first characters of the file, with nothing before it.
What exit code does exec format error give?
Exit code 255, whether the cause is an ARM binary, a script with no #! line, or a script with Windows line endings (which shows no such file or directory instead).
Go further on Hubfly space
- Ship a small Go image: the two-stage Dockerfile, health checks and the errors that break first deploys. How to deploy a Go app with Docker using a tiny image.
- When the build itself fails: find the one log line that explains it. Build failed? How to read the build log and fix it fast.
- Build on every push: let GitHub Actions trigger a build after your tests pass, so nobody pushes an image from a laptop. How to deploy on every push with a GitHub Actions webhook.
By Octave · drafted with AI, tested on Hubfly · Last updated 19 November 2026






