Docker exit code 126 occurs when a command in your container specification is found but cannot be executed. This typically happens when entrypoint scripts or executable files lack proper execute permissions, preventing the container from starting successfully.
Exit code 126 is a standard Unix/Linux exit code that indicates a command or script exists but cannot be invoked. In Docker contexts, this means that the container runtime found the specified command (such as an entrypoint script or CMD executable) but was unable to execute it. This is distinct from exit code 127, which indicates the command was not found at all. With exit code 126, the file exists in the expected location but lacks the necessary permissions or proper file format to be executed by the container runtime. The error typically manifests during container startup when Docker attempts to run your ENTRYPOINT or CMD instruction. The container will start briefly, fail to execute the command, and immediately exit with code 126.
First, identify exactly which file is causing the exit code 126 error:
docker logs <container-id>
# or
docker-compose logs <service-name>Look for error messages like:
- exec: "/entrypoint.sh": permission denied
- /usr/local/bin/docker-entrypoint.sh: Permission denied
- cannot execute binary file
This tells you which file needs permissions fixed.
The most reliable fix is to add execute permissions directly in your Dockerfile before the file is used:
# Copy your script
COPY entrypoint.sh /usr/local/bin/
# Make it executable
RUN chmod +x /usr/local/bin/entrypoint.sh
# Use it as entrypoint
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]Place the chmod command immediately after copying the file and before it's used in ENTRYPOINT or CMD. This ensures permissions are set correctly in all environments.
If you're developing on Windows, your shell scripts may have Windows line endings (CRLF) which prevent them from executing on Linux containers:
Option 1: Fix locally before building
# Convert line endings (Linux/Mac)
dos2unix entrypoint.sh
# Or using sed
sed -i 's/\r$//' entrypoint.shOption 2: Fix in Dockerfile
COPY entrypoint.sh /usr/local/bin/
RUN sed -i 's/\r$//' /usr/local/bin/entrypoint.sh && \
chmod +x /usr/local/bin/entrypoint.shOption 3: Configure Git (preventative)
Add to your .gitattributes file:
*.sh text eol=lfThis ensures Git always checks out shell scripts with Unix line endings.
If you prefer to set permissions before building, make the file executable on your host system:
# Make script executable
chmod +x entrypoint.sh
# Verify it has execute permissions
ls -la entrypoint.sh
# Should show: -rwxr-xr-xThen rebuild your Docker image. However, note that this approach can be less reliable across different operating systems and Git configurations. The Dockerfile approach (step 2) is generally more robust.
If you're using Docker BuildKit (Docker 20.10+), you can set permissions directly in the COPY instruction:
# Enable BuildKit features
# syntax=docker/dockerfile:1
FROM ubuntu:22.04
# Copy with execute permissions
COPY --chmod=755 entrypoint.sh /usr/local/bin/entrypoint.sh
ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]This is the most elegant solution but requires BuildKit to be enabled:
# Build with BuildKit
DOCKER_BUILDKIT=1 docker build -t myimage .After applying the fix, rebuild your image without using cache to ensure changes take effect:
# Rebuild without cache
docker build --no-cache -t myimage .
# Run the container
docker run myimage
# Check exit code
docker ps -a
# Should show "Exited (0)" instead of "Exited (126)"If the container still exits with code 126, inspect the filesystem inside the container to verify permissions:
# Override entrypoint to inspect
docker run --rm --entrypoint ls myimage -la /usr/local/bin/entrypoint.shThe file should show execute permissions (x flags in the permission string).
Architecture Mismatches: Exit code 126 can also occur when trying to execute a binary compiled for a different architecture. For example, attempting to run an ARM64 binary in an AMD64 container will fail with "cannot execute binary file: Exec format error" and exit code 126. Use multi-architecture builds or ensure your base image matches your binary architecture.
SELinux Contexts: On systems with SELinux enabled (like RHEL/CentOS), files copied from the host may have incorrect security contexts. If you encounter this in production, you may need to adjust SELinux policies or run the container in permissive mode (not recommended for production).
Shebang Line Issues: Ensure shell scripts have a proper shebang line (#!/bin/sh or #!/bin/bash) as the first line. A missing or incorrect shebang can cause exec format errors. Also verify that the interpreter specified in the shebang exists in your container image.
Non-Executable File Formats: If you accidentally COPY a text file, Word document, or other non-executable format where Docker expects an executable, you'll get exit code 126. Verify your COPY commands are copying the correct files.
Docker Compose Considerations: When using docker-compose, ensure your entrypoint scripts are in the correct location relative to your docker-compose.yml file, and that volume mounts aren't overwriting executable files with non-executable versions from the host.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub