How to fix OCI runtime exec failed: exec failed: unable to start container process in Docker

DockerINTERMEDIATEMEDIUM

The OCI runtime exec failed error occurs when Docker's container runtime cannot start or execute a process inside a container. This typically happens due to missing executables, incorrect shell paths, containerd/runc bugs, or line ending issues in scripts.

What this error means

This error originates from Docker's OCI (Open Container Initiative) runtime layer, specifically the runc or containerd components that manage container processes. When you see "OCI runtime exec failed: exec failed: unable to start container process," it means the container runtime attempted to start or execute a command but encountered a fundamental issue that prevented the process from launching. The error can occur during `docker run` (when starting a container) or `docker exec` (when executing commands in a running container). The root cause is usually one of several system-level problems: the executable doesn't exist at the specified path, the wrong shell interpreter is being used, there's a bug in the runtime components, or file permissions and line endings are causing issues. Understanding this error requires recognizing that Docker containers run processes through multiple layers: Docker CLI → Docker daemon → containerd → runc → container process. When any link in this chain fails to properly initialize the process, you'll see this error message.

How to fix "OCI runtime exec failed: exec failed: unable to start container process"

1Verify the executable exists in your container

First, check if the command you're trying to run actually exists in the container. Use docker run with a shell to inspect:

bash

docker run -it <image> /bin/sh
# or
docker run -it <image> /bin/bash

Once inside, check if the executable exists:

bash

which <command>
ls -la /path/to/executable

If the command doesn't exist, you need to install it in your Dockerfile or change your CMD/ENTRYPOINT to use an available executable.

2Use the correct shell for your base image

Alpine Linux and other minimal images often don't include bash. Check which shell is available and update your commands accordingly:

dockerfile

# For Alpine-based images, use /bin/sh instead of /bin/bash
FROM alpine:latest
CMD ["/bin/sh", "-c", "echo hello"]

# For Ubuntu/Debian images, bash is usually available
FROM ubuntu:latest
CMD ["/bin/bash", "-c", "echo hello"]

When using docker exec, match the shell to what's available:

bash

# Use sh for Alpine
docker exec -it container_name /bin/sh

# Use bash for Ubuntu/Debian
docker exec -it container_name /bin/bash

3Fix path formatting and quoting issues

Ensure you're using correct Linux path formatting:

bash

# WRONG - backslashes don't work on Linux
CMD ["\bin\sh", "-c", "echo hello"]

# CORRECT - use forward slashes
CMD ["/bin/sh", "-c", "echo hello"]

# WRONG - quoting the entire command
docker exec container "/bin/sh -c 'ls'"

# CORRECT - separate arguments
docker exec container /bin/sh -c "ls"

Use the full path to executables or add directories to PATH:

dockerfile

# Option 1: Use full path
CMD ["/usr/local/bin/myapp"]

# Option 2: Update PATH
ENV PATH="/app/bin:$PATH"
CMD ["myapp"]

4Convert script line endings to Unix format

If you're copying scripts from Windows, they may have CRLF line endings that cause execution failures. Convert them to LF:

Using dos2unix:

bash

dos2unix script.sh

In your Dockerfile, you can fix line endings during the build:

dockerfile

COPY script.sh /app/
RUN sed -i 's/\r$//' /app/script.sh && \
    chmod +x /app/script.sh

In Git, configure proper line ending handling:

bash

# Set in .gitattributes
*.sh text eol=lf

Verify shebang lines in scripts are correct:

bash

#!/bin/sh
# NOT: #!/bin/bash (if bash isn't installed)

5Update containerd/runc if you're on buggy versions

Containerd 1.6.7 and runc 1.1.3 had bugs causing "operation not permitted" errors. Update to fixed versions:

Check current versions:

bash

docker info | grep -i runtime
containerd --version
runc --version

Update containerd (fixes 1.6.7 regression):

bash

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install containerd.io

# Verify version is 1.6.8 or higher
containerd --version

Update runc (fixes 1.1.3 bug):

bash

# Download latest runc
wget https://github.com/opencontainers/runc/releases/download/v1.1.4/runc.amd64
sudo install -m 755 runc.amd64 /usr/local/sbin/runc
runc --version

After updating, restart Docker:

bash

sudo systemctl restart docker

Restart your containers:

bash

docker stop <container_id>
docker start <container_id>

6Install missing packages in your container

If the error occurs because a required executable isn't installed, add it to your Dockerfile:

dockerfile

# For Alpine
FROM alpine:latest
RUN apk add --no-cache bash curl wget

# For Ubuntu/Debian
FROM ubuntu:latest
RUN apt-get update && apt-get install -y \
    bash \
    curl \
    wget \
    && rm -rf /var/lib/apt/lists/*

For existing containers, you can temporarily install packages:

bash

# Alpine
docker exec container apk add bash

# Ubuntu/Debian
docker exec container apt-get update && apt-get install -y bash

However, always prefer rebuilding your image with the proper dependencies rather than modifying running containers.

How to fix OCI runtime exec failed: exec failed: unable to start container process in Docker

What this error means

Typical symptoms

Common causes

How to fix "OCI runtime exec failed: exec failed: unable to start container process"

Advanced notes

Related errors

Official resources & further reading