Docker OCI Runtime Exec Format Error: Causes and Fixes

Start with the exact executable named in the error

A common message looks like this:

OCI runtime create failed: runc create failed: unable to start container process:
exec: "/usr/local/bin/docker-entrypoint.sh": exec format error

The quoted path is the first process the runtime attempted to start. It may come from the image's ENTRYPOINT, its CMD, a Compose command or entrypoint override, or a command supplied directly to docker run. Inspect the effective runtime configuration before editing the Dockerfile:

docker image inspect your-image
docker inspect your-container
docker compose config

A bind mount can replace a correct entrypoint from the image with a malformed host file. Compose expansion can also choose a different image, platform, or command from the one you expected.

Cause 1: image and host CPU architectures do not match

Linux containers share the host kernel. A binary built for x86-64 cannot run natively on an ARM64 host, and the reverse is also true. Docker Desktop may provide emulation for selected combinations, but a standalone engine needs compatible binaries or correctly registered emulation.

docker info
docker image inspect your-image
docker buildx imagetools inspect registry.example/your-image:tag

In the inspect output, compare the image's architecture and operating system with the engine host. For a registry image, the imagetools command shows whether the tag points to a multi-platform manifest and which variants it contains.

If only one architecture was published, rebuild for the platforms you actually support. A typical multi-platform build looks like this:

docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.example/your-image:tag --push .

Ensure the build really produces platform-native application binaries. Copying an amd64 binary into both image variants still creates a broken ARM image, even if the base image changes correctly.

Why it works locally but fails on another host

A local machine may transparently run a foreign architecture through Docker Desktop emulation while a Linux production host has no equivalent emulator. The same tag can also point to a manifest list that selects a different image per host. Compare the immutable image digest and selected platform, not only the human-readable tag. A tag can be moved, and separate hosts can retain different cached variants.

docker image inspect your-image
docker buildx imagetools inspect registry.example/your-image:tag
docker pull --platform linux/arm64 registry.example/your-image:tag

The explicit pull is a diagnostic and deployment-control technique, not a substitute for publishing the correct manifest. Pin production deployments to an expected digest when reproducibility matters, and make platform support visible in release testing.

Cause 2: the entrypoint script has no valid shebang

A text script executed directly needs an interpreter directive on the first line. Valid examples include #!/bin/sh and #!/usr/bin/env python3. The interpreter must exist inside the final image, not merely in the build stage or on the host.

docker run --rm --entrypoint /bin/sh your-image -c \
  'head -n 1 /usr/local/bin/docker-entrypoint.sh; file /usr/local/bin/docker-entrypoint.sh'

This inspection command works only if the image contains /bin/sh and that shell is compatible with the image platform. For a distroless image, inspect the relevant build stage or export the image filesystem instead.

Cause 3: CRLF line endings damaged the interpreter path

A script committed or generated with Windows CRLF endings can make the first line effectively point to /bin/sh plus an invisible carriage return. The runtime then cannot locate a valid interpreter. Normalize scripts to LF before the image layer is built.

file docker-entrypoint.sh
sed -n '1l' docker-entrypoint.sh
dos2unix docker-entrypoint.sh

Add an appropriate .gitattributes rule when the repository must preserve LF for shell scripts across platforms. Rebuild without reusing the stale copy layer if necessary.

Cause 4: the file is not the kind of executable you think it is

The path can point to a damaged download, HTML error page, public key, compressed archive, or binary for another operating system. Use file during the image build and fail early if an external artifact is unexpected. Verify checksums for downloaded release assets and choose the artifact that matches both Linux and the target CPU architecture.

Distinguish format errors from nearby failures

• permission denied usually points to executable mode, directory permissions, mount policy, or container identity.
• no such file or directory can mean the executable or its shebang interpreter is absent.
• executable file not found in PATH means the command name did not resolve inside the container.
• exec format error means the kernel did not recognize a runnable format for the selected file and environment.

These messages overlap around entrypoint mistakes, so inspect the exact quoted path, image platform, file type, and first line together.

Check the build stage and final stage separately

Multi-stage builds can compile correctly in one stage and copy the wrong output into another. Pin stage platforms deliberately when cross compiling. Docker exposes build arguments such as TARGETOS, TARGETARCH, and BUILDPLATFORM for platform-aware build logic. Print or validate these values during troubleshooting rather than assuming what BuildKit selected.

Prevent the error in continuous integration

Building a manifest is not enough. Run a smoke test that starts each published platform variant and executes the real entrypoint. Validate script line endings and executable modes in the repository, and verify downloaded binary checksums and architecture during the build. These checks turn an immediate production start failure into a controlled build failure with a much clearer message.

A reliable fix sequence

1. Capture the complete OCI runtime error and the executable path it names.
2. Render Compose configuration and inspect the image's effective entrypoint and command.
3. Compare engine architecture, image architecture, and registry manifest variants.
4. Inspect the executable type, shebang, line endings, and interpreter inside the final image.
5. Rebuild for the intended platform and verify the new image digest before retesting.
6. Run the image on every platform variant you publish.

Authoritative references

Docker's multi-platform build documentation explains why container code must match the host architecture and how manifest lists select variants. The Dockerfile reference documents ENTRYPOINT, CMD, and platform controls that determine the process the runtime attempts to execute.