Docker "exec format error": Causes and Solutions

The "exec /usr/bin/sh: exec format error" is a common Docker error that occurs when there's a mismatch between the architecture of your Docker image and the system trying to run it. This comprehensive guide covers the main causes and solutions for this frustrating error.

Problem Overview

When Docker encounters this error, it means the system cannot execute a binary or script because it's in an incompatible format. This typically happens when:

• The image was built for a different CPU architecture (ARM vs x86)
• Scripts are missing proper headers (shebang lines)
• File permissions or encoding issues exist
• Corrupted Docker images or build system problems

Primary Cause: Architecture Mismatch

The most common cause is building an image on one architecture (e.g., ARM64) and trying to run it on another (e.g., AMD64/x86_64).

Identifying Architecture Issues

Check your image architecture:

docker image inspect your-image-name:tag

Look for these fields in the output:

"Architecture": "arm64",
"Variant": "v8", 
"Os": "linux",

Compare this with your host system's architecture:

docker version
# Look for OS/Arch in both Client and Server sections

Solutions for Architecture Mismatch

1. Build for the Target Platform

Use --platform flag to specify the target architecture during build:

docker build --platform="linux/amd64" -t your-image-name .

2. Specify Platform in Dockerfile

Set the platform for the base image in your Dockerfile:

FROM --platform=linux/amd64 ubuntu:20.04
RUN apt-get update
RUN apt-get install -y software-properties-common
RUN apt-get install -y python3-pip
RUN pip3 install robotframework

3. Use Docker Buildx for Multi-Architecture Builds

Enable Buildx and create a builder instance:

docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t your-image-name .

Other Common Causes and Solutions

Missing Shebang Line

Scripts executed in Docker containers must begin with a proper shebang line:

#!/bin/bash
# Your script commands here
echo "Script running"

WARNING

Without the #!/bin/bash or #!/bin/sh shebang, the system doesn't know how to interpret your script, resulting in the "exec format error".

File Permission Issues

Ensure your scripts have execute permissions:

# Set execute permission
chmod +x your-script.sh

# Verify permissions
ls -la your-script.sh

File Encoding Problems

Use proper text encoding (UTF-8) and Unix line endings (LF instead of CRLF):

# Convert line endings if needed
sed -i 's/\r$//' your-script.sh

Corrupted Docker Images

Sometimes Docker's build cache or images can become corrupted:

# Clean up Docker system (use with caution)
docker system prune -a

# Remove specific image
docker rmi your-image-name

GitLab CI/CD Specific Solutions

For GitLab runners, ensure your runner architecture matches your image architecture:

robot-framework:
  image: your-custom-image:tag
  tags:
    - linux-amd64  # Match runner tag to architecture
  script:
    - ls
    - pip3 --version

Complete Working Example

Here's a corrected Dockerfile and CI configuration:

FROM --platform=linux/amd64 ubuntu:20.04

RUN apt-get update && \
    apt-get install -y software-properties-common python3-pip && \
    pip3 install robotframework

# Set working directory
WORKDIR /app

# Example entrypoint script with proper shebang
COPY entrypoint.sh .
RUN chmod +x entrypoint.sh

ENTRYPOINT ["./entrypoint.sh"]

#!/bin/bash
echo "Container started"
exec "$@"

robot-framework:
  image: your-registry/rf:v1
  script:
    - pip3 --version
    - robot --version

Troubleshooting Checklist

When encountering "exec format error":

1. ✅ Verify image and host architecture match
2. ✅ Check script permissions (chmod +x)
3. ✅ Ensure proper shebang lines in scripts
4. ✅ Validate file encoding and line endings
5. ✅ Clean Docker cache if suspected corruption
6. ✅ Use explicit platform flags in builds

Advanced: Multi-Platform Build Setup

For production environments, set up proper multi-architecture builds:

# Create and use buildx builder
docker buildx create --name multiarch --use

# Build for multiple platforms
docker buildx build --platform linux/amd64,linux/arm64 -t your-image:latest .

# Push to registry
docker buildx build --platform linux/amd64,linux/arm64 -t your-image:latest --push .

TIP

Modern Docker Desktop installations include Buildx by default. On Linux systems, you may need to install it separately via your package manager.

Conclusion

The "exec format error" in Docker typically stems from architecture mismatches between build and runtime environments. By explicitly specifying target platforms, ensuring proper script formatting, and maintaining clean build environments, you can avoid this common pitfall and ensure your containers run reliably across different systems.