How to fix exec format error (using QEMU emulation) in Docker

What this error means

The "exec format error" when using QEMU emulation indicates that Docker cannot execute binaries inside a container because they were compiled for a different CPU architecture than your host system, and the QEMU emulation layer is either missing, misconfigured, or encountering issues. Docker containers share the host kernel, which means the executable code inside the container must be compatible with the host's processor architecture. When you try to run a container built for ARM64 (aarch64) on an x86_64 machine, or an x86_64 container on an Apple Silicon Mac (ARM64), the system needs QEMU's user-mode emulation to translate instructions between architectures. This error commonly appears as `standard_init_linux.go:XXX: exec user process caused "exec format error"` or `exec /bin/sh: exec format error`. It means the Linux kernel tried to execute a binary but couldn't find a suitable handler for its format - either because QEMU isn't installed, the binfmt_misc handlers aren't registered, or the binary itself has issues like incorrect shebangs or Windows-style line endings.

Typical symptoms

• Container immediately exits with 'exec format error' when starting
• Error message: 'standard_init_linux.go:XXX: exec user process caused exec format error'
• Docker exec commands fail with '/bin/sh: exec format error'
• Multi-architecture builds fail during the RUN instruction
• CI/CD pipelines crash when building for different architectures
• Containers work on Docker Desktop but fail on Linux servers
• ENTRYPOINT or CMD scripts fail to execute despite correct paths
• Images pulled from registries fail to start on ARM-based hosts like Raspberry Pi or AWS Graviton

Common causes

1. QEMU user-mode emulation is not installed on the host system (most common on Linux servers)
2. binfmt_misc handlers are not registered for the target architecture
3. The container image architecture doesn't match the host and no emulation is available
4. QEMU persistent mode is not enabled, and the interpreter is not available inside the container
5. Building multi-platform images without proper buildx configuration
6. Docker Desktop's QEMU integration is broken or not started properly
7. Script files in the image have Windows-style line endings (CRLF instead of LF)
8. Missing or incorrect shebang (#!) in script used as ENTRYPOINT or CMD
9. Using /bin/bash on Alpine Linux which only has /bin/sh
10. Binary compiled for wrong architecture included in the image

How to fix "exec format error (using QEMU emulation)"

# On Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y qemu qemu-user-static binfmt-support

# On Fedora/CentOS/RHEL
sudo dnf install qemu-user-static

# On Arch Linux
sudo pacman -S qemu-user-static qemu-user-static-binfmt

# Check for registered handlers
ls /proc/sys/fs/binfmt_misc/

# You should see entries like qemu-aarch64, qemu-arm, etc.

# Register all QEMU handlers with persistent mode
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# Verify it worked by running an ARM container on x86
docker run --rm arm64v8/alpine uname -m
# Should output: aarch64

# Or x86 on ARM
docker run --rm amd64/alpine uname -m
# Should output: x86_64

# Create and use a new builder with multi-platform support
docker buildx create --name mybuilder --use --bootstrap

# Verify QEMU platforms are available
docker buildx inspect --bootstrap
# Should show platforms like: linux/amd64, linux/arm64, linux/arm/v7, etc.

# Build for a specific platform
docker buildx build --platform linux/arm64 -t myimage:arm64 .

# Build multi-platform image
docker buildx build --platform linux/amd64,linux/arm64 -t myimage:latest --push .

# Run ARM container on x86 with explicit platform
docker run --platform linux/arm64 arm64v8/ubuntu:22.04 uname -m

# Run x86 container on ARM (e.g., Apple Silicon)
docker run --platform linux/amd64 ubuntu:22.04 uname -m

# Pull with specific platform
docker pull --platform linux/arm64 nginx:latest

export DOCKER_DEFAULT_PLATFORM=linux/amd64
docker run ubuntu:22.04 uname -m  # Will use amd64

# Check for Windows line endings (CRLF)
file your-script.sh
# Bad: "your-script.sh: ASCII text, with CRLF line terminators"
# Good: "your-script.sh: ASCII text"

# Convert to Unix line endings
sed -i 's/\r$//' your-script.sh
# Or use dos2unix
dos2unix your-script.sh

# Copy and fix line endings
COPY entrypoint.sh /entrypoint.sh
RUN sed -i 's/\r$//' /entrypoint.sh && chmod +x /entrypoint.sh

#!/bin/bash  # Requires bash to be installed
#!/bin/sh   # More portable, works on Alpine
#!/usr/bin/env python3  # For Python scripts

# Inspect local image architecture
docker image inspect myimage:latest --format '{{.Os}}/{{.Architecture}}'

# Check remote image platforms
docker buildx imagetools inspect nginx:latest
# Shows all available platforms in the manifest

# Check your host architecture
uname -m
# x86_64 = linux/amd64
# aarch64 = linux/arm64
# armv7l = linux/arm/v7

name: Build Multi-Arch
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Required for cross-platform builds
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: user/app:latest

# Restart Docker daemon
sudo systemctl restart docker

# Re-register QEMU handlers
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# On Docker Desktop, restart via the GUI or:
# macOS
killall Docker && open -a Docker

# Windows (PowerShell as Admin)
Restart-Service docker

sudo systemctl status binfmt-support
sudo systemctl restart binfmt-support

Advanced notes

# 1. Check binary format
file /path/to/binary
# Look for architecture: "ELF 64-bit LSB executable, ARM aarch64"

# 2. Verify binfmt registration
cat /proc/sys/fs/binfmt_misc/qemu-aarch64
# Should show "enabled" and correct interpreter path

# 3. Test QEMU directly
qemu-aarch64-static /path/to/arm64/binary

# 4. Check QEMU is accessible
which qemu-aarch64-static
ls -la /usr/bin/qemu-*-static

docker run --privileged --rm tonistiigi/binfmt --install all

# Install specific architectures only
docker run --privileged --rm tonistiigi/binfmt --install arm64,arm

Frequently asked questions

What does "exec format error (using QEMU emulation)" mean?

The "exec format error" when using QEMU emulation indicates that Docker cannot execute binaries inside a container because they were compiled for a different CPU architecture than your host system, and the QEMU emulation layer is either missing, misconfigured, or encountering issues. Docker containers share the host kernel, which means the executable code inside the container must be compatible with the host's processor architecture. When you try to run a container built for ARM64 (aarch64) on an x86_64 machine, or an x86_64 container on an Apple Silicon Mac (ARM64), the system needs QEMU's user-mode emulation to translate instructions between architectures.

How do I fix "exec format error (using QEMU emulation)"?

This error occurs when Docker attempts to run a container built for a different CPU architecture using QEMU emulation, but the emulation fails or is not properly configured. Common when running ARM images on x86 machines or vice versa. The fix involves properly setting up QEMU binfmt handlers or building native multi-architecture images.

What causes "exec format error (using QEMU emulation)"?

QEMU user-mode emulation is not installed on the host system (most common on Linux servers) binfmt_misc handlers are not registered for the target architecture The container image architecture doesn't match the host and no emulation is available

Is the "exec format error (using QEMU emulation)" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• toomanyrequests: You have reached your pull rate limit

  How to fix 'You have reached your pull rate limit' in Docker

  MEDIUM

• Error response from daemon: repository does not exist

  How to fix 'repository does not exist' when pushing Docker images

  MEDIUM

• toomanyrequests: Rate exceeded for anonymous users

  How to fix 'Rate exceeded for anonymous users' in Docker Hub

  MEDIUM

• denied: requested access to the resource is denied

  How to fix 'requested access to the resource is denied' in Docker

  LOW

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Docs - Multi-platform builds(Official Docs)
• 🐙
  multiarch/qemu-user-static - QEMU Docker setup(GitHub)
• 💬
  Stack Overflow - docker buildx exec format error(Stack Overflow)
• 💬
  Stack Overflow - exec format error on Arm64(Stack Overflow)
• 💬
  Stack Overflow - standard_init_linux.go exec format error(Stack Overflow)
• 📝
  Baeldung - Docker Build and Run Platforms
• 📝
  100 Common Docker Errors & Solutions