Troubleshooting

Exec format error: why Linux, zsh and Docker cannot execute a binary file

Fix exec format error: cannot execute binary file on Linux, zsh and Docker. Check uname -m and file, then fix the architecture, shebang or download.

Published ~8 min read
On this page

Short answer: “Exec format error” means the kernel does not recognise the file as something it can start. Most often it is a binary built for another CPU (an ARM64 build on an x86_64 server, or the reverse). The rest are files that are not programs at all: a script without a #! first line, an HTML error page saved instead of the download, an archive, or a macOS or Windows build. Compare the file with the machine:

diagnose in ten seconds
uname -m                                  # this machine: x86_64 or aarch64
file ./program                            # what the file really is
readelf -h ./program | grep -E 'Class|Machine'   # ELF binaries only
head -c 200 ./program                     # scripts and failed downloads show up as text

x86_64 from uname -m and ARM aarch64 from file means: get the amd64 build. Anything else file prints is in the table below.

What the error looks like in bash, sh, zsh and Docker

Every variant comes from the same kernel error, ENOEXEC, which the execve(2) man page describes as an executable that “is not in a recognized format, is for the wrong architecture” or has another format error. Only the wording changes:

ProgramMessageExit status
bashbash: ./program: cannot execute binary file: Exec format error126
sh (dash on Debian and Ubuntu)sh: 1: ./program: Exec format error126
zshzsh: exec format error: ./program126
Dockerexec /usr/local/bin/docker-entrypoint.sh: exec format errorcontainer exits
systemdExec format error in the journal, unit fails with 203/EXECservice fails
Python subprocessOSError: [Errno 8] Exec format errorexception

The bash, sh and Python lines are what bash 5.2, dash and Python 3.11 gave on our Debian 12 host (bash adds line 1: when the command comes from bash -c). The zsh wording and its 126 come from the zsh source, Src/exec.c and Src/utils.c. 126 means “found but could not be run”, 127 means “not found”, see exit code 127.

Fast diagnosis: what does file say?

file printsCauseFix
ELF 64-bit ... ARM aarch64ARM64 build on an x86_64 machineDownload or build the x86_64 / amd64 version
ELF 64-bit ... x86-64x86_64 build on an ARM machine (Raspberry Pi, ARM server, container on an Apple silicon Mac)Download or build the aarch64 / arm64 version
HTML documentThe download saved an error or login pageDownload again with the exact release URL
gzip compressed data, Zip archive, XZ compressed dataAn archive, not the program inside itExtract it, then run the binary from the folder
Mach-O 64-bit ... executablemacOS buildUse the Linux build
PE32+ executable ... MS WindowsWindows .exeUse the Linux build
ASCII text (no “script”)Script without a shebang, or with a blank line above itPut #!/bin/sh or #!/bin/bash on line 1
(with BOM)UTF-8 byte order mark before the #!Strip the BOM
UTF-16 or just dataScript saved as UTF-16, called Unicode in some Windows editorsConvert to UTF-8 with iconv

Cause 1: a binary for the wrong CPU architecture

Linux on a server is almost always one of two architectures, and every project names them differently in its download list:

  • x86_64, also written amd64, x64 or x86-64: Intel and AMD processors. uname -m prints x86_64.
  • aarch64, also written arm64 or armv8: 64-bit ARM, such as ARM cloud servers, a Raspberry Pi with a 64-bit OS, and Linux containers on Apple silicon Macs. uname -m prints aarch64.

To show what the mismatch looks like without a second machine, we copied /bin/ls on our x86_64 Debian 12 host and changed the two-byte machine field of its ELF header to AArch64. file 5.44 and readelf 2.40 then report it like any real ARM64 build, and the kernel refuses to start it:

output · Debian 12, x86_64
$ uname -m
x86_64
$ file ./ls-arm64
./ls-arm64: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), dynamically linked, ...
$ readelf -h ./ls-arm64 | grep -E 'Class|Machine'
  Class:                             ELF64
  Machine:                           AArch64
$ readelf -h /bin/ls | grep Machine
  Machine:                           Advanced Micro Devices X86-64
$ bash -c ./ls-arm64; echo $?
bash: line 1: ./ls-arm64: cannot execute binary file: Exec format error
126

One trap: started through env (and other tools that use the C library’s execvp), the same file did not print “Exec format error” at all. On ENOEXEC, glibc hands the file to /bin/sh as a script, and dash answered with ./ls-arm64: 1: Syntax error: ";" unexpected. A shell syntax error about a binary file is the same architecture problem.

What about 32-bit binaries?

A 32-bit x86 program (file says ELF 32-bit ... Intel 80386) normally runs on a 64-bit x86 kernel (Debian’s is built with CONFIG_IA32_EMULATION=y). When it fails, it is usually “No such file or directory” for the missing 32-bit loader, see error while loading shared libraries. A kernel built without IA32 emulation, or booted with ia32_emulation=false, which per the kernel documentation “unconditionally disables IA32 emulation”, cannot load them at all and answers with Exec format error.

Cause 2: a script the kernel does not recognise

The kernel only treats a file as a script when its first two bytes are #!. Anything in front of them (a blank line, a byte order mark, UTF-16 encoding) or no shebang at all leaves a file the kernel cannot run. What you see then depends on who started it: bash and dash catch ENOEXEC and run a text file as a shell script themselves, while Docker, systemd and language runtimes that call execve directly get the bare error. We ran each variant three ways on Debian 12:

Filebash ./filesh ./fileDirect execve (Docker, systemd)
No shebangRuns itRuns itExec format error
Blank line, then #!Runs itRuns itExec format error
UTF-8 BOM before #!Prints #!/bin/bash: No such file or directory, then runs the restSame, with not foundExec format error
UTF-16 encodedcannot execute binary file: Exec format errorExec format errorExec format error
Shebang ends in CRLFcannot execute: required file not foundnot foundNo such file or directory
Shebang names an ARM64 interpreterRuns it with bashRuns it with shExec format error

Two results are worth remembering. First, CRLF line endings do not cause Exec format error: a #!/bin/bash line ending in a carriage return makes the kernel look for a program called /bin/bash\r, and that is a “No such file or directory” (“bad interpreter” in bash 5.1 and 5.3) error. Second, a script that works in your terminal can still fail in a container or a systemd unit, because only the shell forgives a missing shebang. That is also why the error names docker-entrypoint.sh when the real problem is the architecture of the /bin/sh it points to.

fix the first line
head -1 script.sh | od -c | head -2       # what is really in front of the #!

sed -i '1s/^\xEF\xBB\xBF//' script.sh      # remove a UTF-8 BOM (GNU sed)
iconv -f UTF-16 -t UTF-8 script.sh > script.new && mv script.new script.sh   # UTF-16 to UTF-8
sed -i '1i #!/bin/sh' script.sh             # add a shebang when there is none
chmod +x script.sh

After the BOM and UTF-16 fixes, file reported Bourne-Again shell script, ASCII text executable for our test copies and both ran. Use #!/bin/bash if the script needs bash features. More on shebangs and running scripts is in how to run a .sh file in Linux, and on the systemd side in how to create a systemd service.

Cause 3: you downloaded something that is not the program

  • An HTML page. A wrong release URL, an expired link or a login wall saves the server’s error page under the program’s name. From bash you then get shell syntax errors such as syntax error near unexpected token `newline'; started directly, it is Exec format error. Check with head -c 200 file, and download with curl -fL -o so an HTTP error stops curl instead of saving the page.
  • An archive. A .tar.gz made executable gave us cannot execute binary file: Exec format error in bash. Unpack it first, see how to extract tar.gz in Linux.
  • A macOS or Windows build. Mach-O and PE32 files are not ELF, so Linux cannot load them. Pick the file with linux in its name.

Docker: exec /usr/local/bin/docker-entrypoint.sh: exec format error

In containers this error nearly always means the image was built for another platform, typically on an Apple silicon Mac (linux/arm64) and then run on an x86_64 server (linux/amd64), or the reverse. Docker names the first file it starts, but every binary in the image has the problem. Check both sides (commands from the Docker documentation; we did not run Docker for this article):

which platform is the image?
uname -m                                                   # the server
docker image inspect --format '{{.Os}}/{{.Architecture}}' myimage
docker buildx imagetools inspect myimage                   # lists every platform in a registry image

Then build for the platform the server has, or for both:

build for the right platform
# one platform, for an x86_64 server
docker buildx build --platform linux/amd64 -t myimage .

# both platforms in one multi-platform image, pushed to a registry
docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/myimage:1.0 --push .

# run a specific platform of a multi-platform image
docker run --platform linux/amd64 myimage
  • In the Dockerfile, FROM --platform=$BUILDPLATFORM runs a build stage natively on the build machine, and the automatic TARGETOS and TARGETARCH arguments tell a compiler such as Go what to cross-compile for.
  • Multi-platform images need the containerd image store. Per Docker’s docs it is the default in Docker Desktop and on fresh installs of Docker Engine 29.0 and later; an Engine upgraded from an older version keeps the classic store until you enable it, or you build with a docker-container builder and push to a registry.
  • Emulation lets an amd64 host run arm64 images (slowly) through QEMU. Docker Desktop includes it; on Linux Docker’s docs give docker run --privileged --rm tonistiigi/binfmt --install all, which registers handlers in the host kernel. Fine for building, a poor choice for production.
  • An entrypoint without a shebang gives the same message on the right architecture, because Docker executes an exec form ENTRYPOINT directly and no shell steps in. Put the #! line first. More on platforms and flags in the docker run command.

Similar errors with a different cause

  • No such file or directory for a file that exists: the shebang interpreter or the loader is missing, often because of CRLF line endings.
  • Permission denied, also exit 126: no execute bit, or a noexec mount.chmod +x does not fix an Exec format error.
  • command not found, exit 127: the program is not on your PATH.

Frequently asked

What does cannot execute binary file: Exec format error mean?

The kernel does not recognise the file as a program it can start on this machine. Most often it is a binary for another CPU architecture, such as an ARM64 build on an x86_64 server. Compare uname -m with the output of file ./program and download the build that matches.

Why does Docker say exec /usr/local/bin/docker-entrypoint.sh: exec format error?

The image was built for a different platform than the host, typically linux/arm64 on an Apple silicon Mac and then run on a linux/amd64 server. Check the image with docker image inspect --format '{{.Os}}/{{.Architecture}}' and rebuild with docker buildx build --platform linux/amd64, or build both platforms at once. An entrypoint script without a #! first line gives the same message.

Can a script without a shebang cause Exec format error?

Yes. The kernel only runs a file as a script when it starts with #!, so a script without that line, with a blank line or a byte order mark in front of it, or saved as UTF-16 fails with Exec format error when Docker, systemd or a program calls it directly. bash and sh hide the problem by running plain text files as shell scripts themselves.

Do Windows line endings (CRLF) cause Exec format error?

No. A shebang line ending in a carriage return makes the kernel look for an interpreter such as /bin/bash followed by an invisible \r, which fails with No such file or directory, shown as bad interpreter or required file not found. Strip the carriage returns with sed -i 's/\r$//' script.sh.

Related articles

All troubleshooting