Fixing Docker exec format error When Deploying From Apple Silicon (ARM64) to Linux x86_64
Resolve standard_init_linux.go exec user process caused: exec format error in Docker and Kubernetes. Build multi-arch linux/amd64 and linux/arm64 images with Docker Buildx and fix entrypoint shebangs.
The container startup crash `exec user process caused: exec format error` (Linux kernel `ENOEXEC`, errno 8) means the host CPU kernel cannot execute the binary specified in your Dockerfile `ENTRYPOINT` or `CMD`. In 85% of cases, this happens because you built the Docker image locally on an Apple Silicon Mac (`M1/M2/M3/M4`, `linux/arm64`) without `--platform linux/amd64` and pushed it to an x86_64 (`amd64`) Linux production server (or vice versa on AWS Graviton / Ampere ARM instances). In the remaining 15% of cases, your `entrypoint.sh` shell script is missing its `#!/bin/sh` shebang header on line 1, has Windows CRLF (`\r\n`) line endings, or starts with a UTF-8 Byte Order Mark (BOM).
Verified Root Causes in Production Environments
- CPU Instruction Set Architecture Mismatch (ARM64 vs AMD64): An ELF binary compiled for 64-bit ARM (`aarch64`) cannot execute natively on an Intel/AMD x86_64 Linux kernel without QEMU binfmt_misc emulation.
- Missing #!/bin/sh Shebang on Entrypoint Scripts: When Docker invokes `ENTRYPOINT ["./entrypoint.sh"]` directly via the `execve()` syscall, the Linux kernel requires the `#!` magic bytes (`0x23 0x21`) on byte 0 of the file.
- Windows CRLF Line Endings (`#!/bin/sh\r`): Checking out a repository on Windows with `core.autocrlf=true` appends a carriage return (`\r`) to the shebang, causing the kernel to look for a non-existent `/bin/sh\r` interpreter.
1. Diagnose Architecture Mismatch Between Image and Host Server
Before rebuilding your image, run `uname -m` on your target deployment server (`x86_64` indicates AMD64; `aarch64` indicates ARM64) and compare it against the `Architecture` field embedded inside your Docker image manifest.
When you run a plain `docker build -t myapp .` on an Apple M1/M2/M3/M4 MacBook, Docker Desktop defaults to building a `linux/arm64/v8` image. When you pull and run that image on an AMD EPYC or Intel Xeon cloud server (such as Vexlo Cloud's x86_64 nodes, DigitalOcean, or AWS EC2 t3/m6i), the Linux kernel rejects the `aarch64` ELF header immediately with `exec format error`.
# 1. Check the CPU architecture of your Linux host VPS
uname -m
# Output: x86_64 (means linux/amd64) OR aarch64 (means linux/arm64)
# 2. Check the architecture baked into your local or pulled Docker image
docker image inspect <image_name>:latest --format '{{.Os}}/{{.Architecture}}'
# 3. Inspect remote registry manifest architectures without pulling the image
docker buildx imagetools inspect ghcr.io/your-org/your-app:latest2. Fix Scenario A: Cross-Compile With Docker Buildx (`--platform linux/amd64,linux/arm64`)
To build an image on an Apple Silicon Mac that runs natively on x86_64 Linux servers (or runs everywhere via a multi-arch OCI manifest list), use `docker buildx build` with the `--platform` flag.
For Go, Rust, or static C/C++ builds, avoid slow QEMU emulation during compilation by using BuildKit's native cross-compilation arguments (`BUILDPLATFORM`, `TARGETOS`, and `TARGETARCH`). This runs the compiler natively on your host CPU while emitting a target-architecture binary.
# syntax=docker/dockerfile:1.7
# Use --platform=$BUILDPLATFORM so the compiler runs at native speed without QEMU lag
FROM --platform=$BUILDPLATFORM golang:1.23-alpine AS builder
ARG TARGETOS
ARG TARGETARCH
WORKDIR /src
COPY . .
# Cross-compile directly to target architecture (e.g. linux/amd64)
RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
go build -ldflags="-s -w" -o /out/server ./cmd/server
FROM alpine:3.20 AS runner
RUN apk add --no-cache ca-certificates
COPY --from=builder /out/server /usr/local/bin/server
ENTRYPOINT ["/usr/local/bin/server"]3. Fix Scenario B: Missing `#!/bin/sh` Shebangs, CRLF Line Endings & Alpine musl
If `docker image inspect` confirms your image architecture already matches the host (`linux/amd64` on `x86_64`), the `exec format error` is caused by your entrypoint script. When you write an executable script in `ENTRYPOINT ["/app/docker-entrypoint.sh"]`, the Linux kernel's `execve()` system call inspects the first two bytes of the file. If line 1 is blank, starts with a comment `# My script`, or contains an invisible UTF-8 BOM (`EF BB BF`) before `#!/bin/sh`, `execve()` fails with `ENOEXEC` (`exec format error`).
Always start your entrypoint script with `#!/bin/sh` on byte 0, strip Windows `\r` carriage returns inside your Dockerfile using `sed -i 's/\r$//'`, and mark the file executable with `chmod +x`.
COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
# Strip Windows CRLF (\r), remove any UTF-8 BOM, and set executable bit
RUN sed -i 's/\r$//' /usr/local/bin/docker-entrypoint.sh && \
sed -i '1s/^\xEF\xBB\xBF//' /usr/local/bin/docker-entrypoint.sh && \
chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]Pre-Deployment Verification Checklist
- Verify `docker image inspect <img_name> --format '{{.Architecture}}'` matches your server (`amd64` for `x86_64`, `arm64` for `aarch64`).
- Build and push from Apple Silicon Macs using `docker buildx build --platform linux/amd64 --push`.
- Ensure byte 0 of `docker-entrypoint.sh` is literally `#!/bin/sh` or `#!/usr/bin/env bash` (Note: `alpine` images only ship with `/bin/sh` unless `bash` is installed).
- Strip Windows CRLF line endings via `sed -i 's/\r$//' entrypoint.sh` inside your Dockerfile.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why does my Docker image work on my MacBook M2/M3 but fail with exec format error on my Ubuntu VPS?
Your MacBook uses an ARM64 (`aarch64`) processor, while your Ubuntu VPS uses an x86_64 (`amd64`) processor. Rebuild the image using `docker buildx build --platform linux/amd64 -t yourrepo/app:latest --push .`.
Why does a script with #!/bin/bash throw exec format error or no such file on Alpine Linux?
Alpine Linux uses BusyBox `/bin/sh` (`ash`) and does not include `/bin/bash` by default. Change your shebang to `#!/bin/sh` or install bash via `RUN apk add --no-cache bash`.
Can I build both ARM64 and AMD64 images in a single command?
Yes. Run `docker buildx create --use` once, then run `docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/user/app:latest --push .` to publish a multi-arch manifest.