Docker OCI runtime exec failed

By Kaveh Alemi·Latchkey

Docker OCI runtime exec failed comes from docker exec, not from starting a container, so to fix docker exec failures you look at the command you asked for and at the state of the container, never at the build. The runtime found the container and could not run the thing you named inside it.

What this error means

A step that pokes at an already running container fails, while the container itself keeps running and the rest of the job looks healthy. The line names the command in quotes and ends in "executable file not found in $PATH", and on older daemons it ends with a further ": unknown". Our recorded run exited 127. The most common version of this in CI is a script that reaches for bash inside an Alpine image, which ships sh and ash and no bash at all, and the same run below shows an sh exec working seconds earlier in the same container.

--- docker exec exec-demo sh -c 'echo alpine has sh'
alpine has sh
--- docker exec exec-demo bash -lc 'echo unreachable'
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH

Docker version 29.7.2, build a7dcaa6
Unable to find image 'alpine:3' locally
3: Pulling from library/alpine
e2de96513ba9: Pulling fs layer
e2de96513ba9: Download complete
6d0606d1815c: Download complete
797dd00a0fc7: Download complete
e2de96513ba9: Pull complete
Digest: sha256:294b683cb724975bec92580e1e685676bd4b50bda910ddb8c51d4cabeaec77e6
Status: Downloaded newer image for alpine:3
--- container status: running
--- docker exec exec-demo sh -c 'echo alpine has sh'
alpine has sh
--- docker exec exec-demo bash -lc 'echo unreachable'
OCI runtime exec failed: exec failed: unable to start container process: exec: "bash": executable file not found in $PATH
[latchkey-bash-wrapper] BEGIN sidecar POST (boot_wait=30s max_time=320s url=http://localhost/diagnose socket=/run/latchkey-self-heal/sock)
[latchkey-bash-wrapper] END sidecar POST ok (attempts=1 http=200)

Exec failed and create failed are different failures

Both wordings start with "OCI runtime" and both end with a missing executable, which is why they get treated as one problem and fixed in the wrong place. The word after the runtime name is the whole diagnosis. "exec failed" means an already running container was asked to run something extra. "create failed" means the container itself could not be started, which is failed to create shim task and a different fix.

The Docker documentation adds the second half of the diagnosis: the command you exec "only runs while the container's primary process (PID 1) is running", and "the command must be an executable", because a chained or quoted command does not work without a shell around it.

Common causes

The binary is not in the image

The ordinary case, and the one the recorded run shows. bash on Alpine is the classic, but curl, ps, git and even sh go the same way on smaller bases. The message names the command in quotes, so the diagnosis is in the error; what it cannot tell you is that the tool was never there rather than removed.

The container is not running any more

Exec needs a live PID 1 to join. A service that exited on a bad config, a compose service in a restart loop, or a container from an earlier step that has already finished all produce a failure at exec time that is really a startup failure. In our experience this is the half of the error people spend the longest on, because the logs they read are the exec logs.

The binary is there and not on PATH

A tool installed into an unusual prefix resolves only by absolute path, and an exec that names it bare gets the same "not found" as a tool that does not exist. The PATH inside the container is the image PATH, which is not the PATH of the step that ran the exec.

The command was a shell line rather than an executable

A pipe, a redirect or a quoted chain needs a shell to interpret it. Docker documents this directly: the command must be an executable, and a chained or quoted command does not work. Wrap it in sh -c and the same line runs.

How to fix it

Exec a shell the image actually ships

1. Use sh by default; reach for bash only in images you know carry it.
2. If you need bash for real, install it in the image rather than hoping.
3. Check once with command -v, which tells you before the pipeline does.

docker exec app sh -c 'command -v bash || echo "no bash in this image"'
# in the Dockerfile, if you decide you need it
# RUN apk add --no-cache bash

Prove the container is running first

Inspect the status and dump the logs when it is not what you expect. This turns an exec error into the startup error that caused it, which is the thing you actually need to fix, and it costs one step.

docker ps --filter name=app --format '{{.Names}} {{.Status}}'
docker inspect -f '{{.State.Status}} {{.State.ExitCode}}' app

Name the binary by absolute path when PATH is in doubt

An absolute path removes the resolution question entirely. Find it once inside the container, then use it in the workflow, and keep the discovery command in the job so a future image change is visible rather than silent.

docker exec app sh -c 'command -v mytool || ls -l /usr/local/bin'
docker exec app /usr/local/bin/mytool --version

Wrap shell syntax in a shell

Pipes, redirects, globs and && are shell features, so they need a shell process. Pass the whole line to sh -c as one argument, and quote it so the outer shell in your workflow leaves it alone.

docker exec app sh -c 'pg_isready -h localhost && echo ok'

The image decides which shell you get

A slim base image is a deliberate choice to ship less, and bash is one of the things it ships less of. Alpine gives you sh, provided by BusyBox; distroless images may give you no shell at all; a scratch image has nothing but your binary. A script written against bash works on the developer laptop, where the image was never the environment, and fails the first time CI runs it against the real container.

Write the exec against the smallest shell you can rely on, or install the one you need in the image on purpose. Both are fine; guessing is not.

# works on Alpine, Debian and most slim images
docker exec app sh -c 'echo "$PATH"'
# only if the image really has bash
docker exec app bash -lc 'echo "$PATH"'

Half of these are a container that already exited

The other reading of the same failure is that there is nothing left to exec into. A service container that crashed on startup, a compose service still in its restart loop, or a container started in an earlier step that finished while the workflow moved on all leave you execing into a container id that is no longer running a process.

Check the state before the exec rather than after the error, and print the logs when it is not up. Two lines turn a confusing runtime error into the startup failure it actually is.

- name: The container has to be up before we exec
  run: |
    state=$(docker inspect -f '{{.State.Status}}' app)
    echo "app is $state"
    [ "$state" = running ] || { docker logs --tail 50 app; exit 1; }
    docker exec app sh -c 'echo ready'

What the runner does about it

No repair, and none is claimed. On the recorded run the wrapper posted the failure to the sidecar and the sidecar answered, and nothing was repaired: the image had no bash before the diagnosis and it had no bash after. Latchkey carries no pattern for this failure, which is correct, because the missing binary is inside an image the runner does not build.

What a runner can do is make the failure cheap to read. The run above prints the container state and a working exec next to the failing one, so the log answers the first two questions anybody asks. Put the same two lines in your own job and this error stops needing a page.

How to prevent it

• Standardize on sh for anything you exec in CI, whatever the base image is.
• Check container state before every exec in a job, and print logs when it is down.
• Bake the tools your scripts need into the image, rather than into the assumption.
• Pin the base image, so a shell that is present today is still present next month.

Frequently asked questions

Related guides

References

• Docker docs: docker exec, what it requires of the command
• Docker docs: Dockerfile reference, exec form and shell form
• aquasecurity/trivy-action#415: exec failed on a missing bash in an action
• Docker documentation
• Docker build cache
• GitHub Actions documentation