How to Resolve Docker exec /usr/bin/sh: exec Format Error

The error exec /usr/bin/sh: exec format error is a common issue faced by developers working with Docker. This error typically arises due to architecture mismatches, improperly built images, or incorrect script configurations. In this article, we’ll explore the causes of this error and provide actionable steps to resolve it.

Understanding the Problem

The error occurs when:

1. Architecture Mismatch: The Docker image is built for one architecture (e.g., ARM) but is being run on another (e.g., x86).
2. Incorrect Shebang: Missing or incorrect shebang (e.g., #!/bin/bash or #!/bin/sh) in the scripts inside the container.
3. File Permissions: The file being executed is not marked as executable.
4. Corrupted Files: Executable files are not in the correct format for the host system.

Docker exec format error: Step-by-Step Solution

1. Check Host and Image Architecture

Ensure that the architecture of your host machine matches the Docker image.

Check Host Architecture

Run the following command on your host:

uname -m

This will output your host’s architecture, e.g., x86_64 or arm64.

Inspect Docker Image Architecture

Use the following command to inspect the architecture of your Docker image:

docker image inspect <image_name> | grep Architecture

Ensure the output matches your host’s architecture.

2. Rebuild the Image for Compatibility

If the architectures do not match, rebuild the Docker image for the correct architecture.

Rebuild for Specific Architecture

Use the --platform flag while building the image:

docker build --platform linux/amd64 -t <image_name>

This ensures the image is built for the amd64 architecture.

Rebuild for Multiple Architectures

To support multiple architectures, use Docker Buildx:

docker buildx build --platform linux/amd64,linux/arm64 -t <image_name>

This creates a multi-architecture image.

3. Verify Shebang in Scripts

Scripts executed inside the container must start with a valid shebang.

Example of Correct Shebang:

#!/bin/bash

Ensure there are no extra spaces or invalid characters before the shebang line.

If your script does not have a shebang, add one and rebuild the image.

4. Set Correct Permissions

Make sure the executable file has the correct permissions.

Set Executable Permissions

Run the following command:

chmod +x <file_name>

This marks the file as executable.

5. Pull Platform-Specific Images

When using public Docker images, ensure you pull the version compatible with your system’s architecture:

docker pull --platform linux/amd64 <image_name>

6. Clean Docker System

Sometimes, cached images or layers cause conflicts. Clean the Docker system to resolve these issues:

docker system prune -a

This command removes unused data, including dangling images and containers.

7. Test Locally Before Deployment

Before pushing an image to production or using it in CI/CD pipelines, test it locally on the same architecture as your production system.

Example Fix

Here’s an example of a Dockerfile causing the issue and how to fix it:

Problematic Dockerfile:

FROM ubuntu:20.04
RUN apt-get update
RUN apt-get install -y python3-pip
CMD ["/usr/bin/sh"]

Corrected Dockerfile:

FROM --platform=linux/amd64 ubuntu:20.04
RUN apt-get update
RUN apt-get install -y python3-pip
CMD ["/bin/bash"]

In this fixed version:

• The --platform flag ensures the image is built for the correct architecture.
• The CMD uses /bin/bash, which is commonly available and compatible.

Best Practices

• Use Docker Buildx for Multi-Architecture Builds: Build images for multiple platforms in one command:

docker buildx build --platform linux/amd64,linux/arm64 -t <image_name>

• Document Supported Architectures: Clearly document supported architectures in your project’s README.md or documentation.
• Test on Multiple Architectures: Use CI/CD pipelines to test your Docker containers on multiple architectures.
• Indicate Platform When Necessary: Always specify the --platform flag when pulling or building images for cross-platform deployments.

Conclusion

The exec /usr/bin/sh: exec format error is a common issue in Docker, particularly when working in multi-platform environments. By following the steps outlined above—ensuring architecture compatibility, verifying scripts, and cleaning up Docker—you can effectively resolve this error and prevent it from recurring.

With these best practices, your Docker workflows will be smoother, more reliable, and ready for cross-platform deployments.