VPS Tutorials
Docker exec format error: AMD64, ARM64, image contents and entrypoints
Compare daemon, image and binary platforms, inspect registry manifests, rebuild for the target and check entrypoint encoding before recreating the service safely.

A container exits immediately with exec /bin/sh: exec format error. If the image came from an Apple Silicon Mac, an ARM machine or another server, compare the target VPS, image platform and executable inside the image first. Reinstalling Docker does not make incompatible binaries run.
exec format error can also come from an entrypoint script's format. Follow the failed file → actual runtime target → image contents. Replace the example repository yourname/myapp, tags and app service name with your own values.
| Symptom | Check first | Avoid an unrelated fix |
|---|---|---|
| no matching manifest while pulling | Whether the tag has the target platform | Repeated daemon restarts |
/bin/sh fails with exec format error | Image platform and available emulation | chmod 777 on an entrypoint |
Your /app/server cannot execute | Binary OS and CPU architecture | Only changing tag or platform |
entrypoint.sh fails | Interpreter line, line endings and file header | Assuming every failure is ARM-related |
| permission denied | Execute permission, mounts and security policy | Treating it as the same format error |
Keep the original error and failed path:
docker compose ps -a
docker compose logs --tail=80 app
Application logs can be empty before the process starts, so retain startup-command errors too. If the only evidence is repeated restarts, see container restart troubleshooting.
Run on the target VPS, not your Mac:
uname -m
docker context show
docker info --format '{{.OSType}}/{{.Architecture}}'
docker image inspect yourname/myapp:2026-10-23 --format '{{.Os}}/{{.Architecture}}'
image inspect inspects a locally available image; it fails if the image is absent and does not list every platform in a remote registry. See Docker inspect.
| OS reports | Common image platform | Meaning |
|---|---|---|
| x86_64 | linux/amd64 | 64-bit x86, used by Intel and AMD |
| aarch64 | linux/arm64 | 64-bit ARM |
| armv7l | linux/arm/v7 | 32-bit ARM, not arm64 |
Check Docker context as well. The CLI may connect to a remote daemon, so uname -m and the Docker server may describe different machines. Establish which daemon you are operating before changing anything.
An ordinary local build on Apple Silicon often targets ARM64; many x86 VPSs require AMD64. Remote builders and explicit platform options can change that, so trust metadata rather than the computer's name.
Inspect the registry manifest using Buildx:
docker buildx imagetools inspect yourname/myapp:2026-10-23
Look for the required platform, such as linux/amd64 or linux/arm64. Unlike local docker image inspect, this queries remote metadata. Authenticate to private registries as authorized and check Buildx installation if unavailable. See imagetools inspect.
no matching manifest means the tag lacks a matching platform, not a network timeout. Choose a compatible official image or rebuild your application. A single-platform manifest can look different from a multi-platform index; a short output does not itself prove corruption.
For one AMD64 VPS, specify that platform in your build environment:
docker buildx build \
--platform linux/amd64 \
-t yourname/myapp:2026-10-23-amd64 \
--push .
This pushes to a registry where you need write permission. Replace the repository, authenticate and use ARM64 instead for an ARM64 VPS. Keep the previous tag and validate the replacement on a test instance before removing your rollback option. See buildx build.
For a single-platform result in the current daemon's local image store, replace --push with --load. Multi-platform loading depends on the builder driver and image store; this single-platform example does not guarantee it.
For AMD64 and ARM64 together:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t yourname/myapp:2026-10-23 \
--push .
Check builder capabilities with docker buildx ls. Native nodes, cross-compilation or QEMU may be needed. Installing Buildx does not enable arbitrary target executables automatically, and compilation/compression under emulation can be much slower; see multi-platform builds.
Inspect the Dockerfile too. If COPY merely copies a binary built on macOS into a Linux image, --platform linux/amd64 does not convert it to Linux AMD64. Build Go, Rust and native Python/Node dependencies using their target-specific toolchains. Correct image metadata does not guarantee every contained executable matches it.
Once the image actually provides the required platform, you can pin it:
services:
app:
image: yourname/myapp:2026-10-23-amd64
platform: linux/amd64
restart: unless-stopped
Compose platform selects the service platform and participates in image selection. It does not transform ARM binaries or install emulation. Forcing AMD64 on an ARM host may still require an emulator. Prefer a native platform for production where possible.
Confirm the original project, environment options, persistent mounts and backup before a maintenance window:
docker compose config --quiet
docker compose pull app
docker compose up -d --no-deps app
docker compose ps app
These commands assume the real project directory and healthy dependencies. Keep custom -f, --env-file and project-name options consistent. Restart alone does not apply a new image configuration; see Compose changes not taking effect. Recreate with persistent data backed up and mounted; deleting volumes is unnecessary.
Check the source file:
file entrypoint.sh
head -n 1 entrypoint.sh
od -An -tx1 -N32 entrypoint.sh
A directly executed shell script needs an interpreter declaration such as #!/bin/sh, and that interpreter must exist in the image. Changing Bash's shebang to sh does not make Bash-specific syntax compatible. See Linux execve for interpreter scripts and architecture errors.
Check UTF-8 BOM, Windows CRLF and the executable bit. CRLF can add a carriage return to the interpreter path, causing an interpreter-not-found error rather than an architecture failure. permission denied needs a separate permissions check. Back up the file, save it as LF without BOM and validate using the required interpreter. Do not batch-replace line endings in binaries.
If the container exits immediately, docker exec generally cannot enter it. Inspect build sources first. To extract an image file, use a dedicated temporary container and docker cp; avoid ad hoc edits inside production containers that cannot be reproduced from source.
Confirm the Docker server architecture, remote tag platform and contained executable all match. Test a real application request and inspect logs for further format errors. Verify persistent mounts and data, and keep the old tag and configuration for rollback.
These commands are diagnostic examples, not evidence of a deployment tested on both CPU families. Identify the failed file, compare platforms, then inspect scripts and the build toolchain. A platform line alone is not the complete repair.