Skip to main content

How to Resolve Python Error "standard_init_linux.go: ... exec user process caused "exec format error"

When running Docker containers, particularly those executing shell scripts (.sh) as their entrypoint or command, you might encounter the cryptic error: standard_init_linux.go:XXX: exec user process caused "exec format error". This error message originates from the container's initialization process and indicates that the Linux kernel inside the container doesn't recognize the format of the file it's trying to execute.

This guide explores the common causes for this error – missing shebangs, architecture mismatches, incorrect line endings, and file encoding issues – and provides clear solutions to fix them.

Understanding the Error: "Exec Format Error"​

At its core, the "exec format error" means the operating system's kernel (specifically, the Linux kernel inside the Docker container) tried to execute a file specified in your Dockerfile's ENTRYPOINT or CMD, but it couldn't understand the file's format as an executable program or a script for a known interpreter. It doesn't recognize the initial bytes of the file as either a valid binary executable for the container's architecture or a script starting with a valid interpreter directive (the shebang).

Cause 1: Missing or Incorrect Shebang (#!) in Script​

For shell scripts (.sh files) intended to be executed directly, the very first line must be a "shebang" line. This tells the kernel which interpreter should be used to execute the rest of the script.

  • Missing Shebang: If the #!... line is absent, the kernel tries to execute the file directly as a binary, which fails for a text script, leading to the error.
  • Incorrect Shebang: If the shebang points to an interpreter that doesn't exist inside the container (e.g., #!/bin/bash in a minimal Alpine image that only has /bin/sh), it can cause a "no such file or directory" error, sometimes manifesting similarly or being the underlying cause mistaken for a format error.

Solution 1: Add/Correct the Shebang​

Ensure the very first line of your executable script (e.g., entrypoint.sh) is the correct shebang for the shell available in your container image.

  • For most Linux distributions (Debian, Ubuntu, CentOS, Fedora) using Bash:

    #!/bin/bash
    # OR (often more portable):
    #!/usr/bin/env bash

    # Rest of your script...
    echo "Starting application..."
    exec "$@"

  • For minimal images like Alpine Linux (which use ash by default, not bash):

    #!/bin/sh
    # Or sometimes: #!/bin/ash

    # Rest of your script...
    echo "Starting application in Alpine..."
    exec "$@"

Crucial Points:

  • The #! must be the absolute first two bytes of the file. No leading spaces or blank lines.
  • Ensure the specified interpreter path (e.g., /bin/bash, /bin/sh) actually exists within your Docker image.
  • Rebuild your Docker image after adding or correcting the shebang in your script file.

Cause 2: CPU Architecture Mismatch (e.g., ARM vs. x86_64/amd64)​

Docker images are built for specific CPU architectures. Trying to run an image built for one architecture (e.g., linux/amd64 or x86_64, common for Intel/AMD desktops/servers) on a host machine with a different architecture (e.g., linux/arm64 or aarch64, common for Raspberry Pi, Apple Silicon M1/M2 Macs) will cause this error. The container's kernel cannot execute binary instructions compiled for the wrong processor type. The reverse (running an ARM image on an AMD64 host) also causes this error.

Solution 2: Build/Use Image for the Correct Target Architecture (--platform)​

You must ensure the Docker image's architecture matches the architecture of the machine where you intend to run the container.

  • Building Multi-Platform Images or Targeting Specific Platforms: Use docker buildx build with the --platform flag.

    # Build for standard Intel/AMD 64-bit Linux servers (MOST COMMON for deployment)
    docker buildx build --platform=linux/amd64 -t your-image-name:tag-amd64 --load . # or --push

    # Build for ARM 64-bit Linux (e.g., Raspberry Pi 4, some cloud instances, M1/M2 Macs *running Linux VMs*)
    docker buildx build --platform=linux/arm64 -t your-image-name:tag-arm64 --load . # or --push

    # Build for multiple platforms at once (pushes manifest list)
    # docker buildx build --platform=linux/amd64,linux/arm64 -t your-image-name:latest --push .

    (Replace your-image-name:tag appropriately. --load builds for your local Docker daemon, --push pushes to a registry).

  • Specifying Platform in Dockerfile FROM: If your base image supports multiple architectures, you can explicitly request one in the FROM instruction. This influences the architecture of subsequent build steps.

    # Request the amd64 variant of the python base image
    FROM --platform=linux/amd64 python:3.10-slim

    # Rest of your Dockerfile...
    COPY ./entrypoint.sh /entrypoint.sh
    RUN chmod +x /entrypoint.sh
    ENTRYPOINT ["/entrypoint.sh"]

    This ensures the base image and potentially subsequent build steps align with your target architecture. Rebuild your image after adding this.

Cause 3: Incorrect Line Endings (Windows CRLF vs. Unix LF)​

Script files edited on Windows often use Carriage Return + Line Feed (\r\n, CRLF) as line endings. Linux/Unix systems (including Linux containers) expect only Line Feed (\n, LF). If a script with CRLF endings is copied into a Linux container, the interpreter (like /bin/bash) might see the extra \r character as part of the command or shebang path, leading to subtle errors often manifesting as "command not found" or sometimes the "exec format error".

Solution 3: Ensure Unix (LF) Line Endings in Script​

Configure your text editor or IDE to save the script file with LF (Unix-style) line endings before you copy it into the Docker image.

  • VS Code: Look for CRLF/LF in the bottom status bar and click it to change to LF.
  • Git: Configure Git to handle line endings correctly (often default on Linux/macOS, might need git config --global core.autocrlf input on Windows).
  • Tools: Use utilities like dos2unix (sudo apt install dos2unix or equivalent) on the file before building the image: dos2unix your_script.sh.

Rebuild your Docker image after ensuring the script uses LF line endings.

Cause 4: Incorrect File Encoding (e.g., UTF-8 with BOM)​

While less common, saving the script file with an encoding that includes a Byte Order Mark (BOM) at the beginning (like UTF-8-BOM) can cause this error. The BOM consists of invisible characters (\xEF\xBB\xBF for UTF-8 BOM) placed at the very start of the file. The Linux kernel sees these BOM bytes instead of the expected #! shebang sequence and fails with the "exec format error".

Solution 4: Save Script as Standard UTF-8 (No BOM)​

Ensure your text editor saves the script file using the standard UTF-8 encoding without a BOM.

  • Most modern editors have settings for encoding (e.g., "UTF-8" vs. "UTF-8 with BOM"). Choose the option without BOM.
  • Check your editor's preferences or file saving options.

Rebuild your Docker image after saving the file with the correct encoding.

Conclusion​

The Docker exec format error indicates the container's kernel cannot execute the specified file, usually your entrypoint or command script.

Check these common causes and apply the corresponding solutions:

  1. Shebang (#!): Ensure the correct shebang (e.g., #!/bin/bash or #!/bin/sh) is the very first line of your script.
  2. Architecture: Build or pull an image matching the CPU architecture of the host machine (--platform=linux/amd64 or --platform=linux/arm64).
  3. Line Endings: Save script files with Unix-style LF line endings, not Windows CRLF.
  4. Encoding: Save script files as UTF-8 without BOM.

Remember to rebuild your Docker image after making changes to scripts, Dockerfiles, or build commands.

Table of Contents