Docker Command Not Found / Executable Missing

Docker exit code 127 signifies that the command specified in the container's `CMD` or `ENTRYPOINT` instruction, or passed directly via `docker run`, could not be found or executed within the container's environment. This typically means the executable is missing, misspelled, or not in the container's PATH.

Common Causes

The executable specified in CMD/ENTRYPOINT is not installed in the container image.
Misspelling of the command or executable name in the Dockerfile or `docker run` command.
The executable's directory is not included in the container's PATH environment variable.
Incorrect file permissions on the executable (e.g., not executable).
Using the shell form of CMD/ENTRYPOINT when the command is not a shell built-in or directly executable without a shell.

How to Fix

1 Verify Command Existence and Path

Inspect your Dockerfile and the container's contents to ensure the command is present and accessible. You can use `docker exec` to manually check for the command within a running container or inspect the image layers.

BASH

$ docker run --rm -it your-image-name sh -c 'ls -l /usr/local/bin/your-command || which your-command'

2 Install Missing Dependencies

If the command is missing, add instructions to your Dockerfile to install it. Ensure the package manager (e.g., `apt`, `apk`, `yum`) is updated and the correct package name is used.

BASH

 $ FROM alpine:latest
RUN apk update && apk add --no-cache your-package-name
CMD ["your-command"]

3 Adjust PATH Environment Variable

If the command exists but isn't found, its directory might not be in the container's PATH. Add the directory containing your executable to the PATH environment variable in your Dockerfile.

BASH

 $ FROM alpine:latest
ENV PATH="/opt/your-app/bin:${PATH}"
CMD ["your-command"]

4 Use Exec Form for CMD/ENTRYPOINT

Prefer the exec form (`["executable", "param1", "param2"]`) over the shell form (`command param1 param2`) for `CMD` and `ENTRYPOINT`, especially for the primary process. The exec form directly executes the command without involving a shell, which can prevent issues if the shell itself is missing or misconfigured.

BASH

 $ FROM alpine:latest
CMD ["/usr/bin/your-command", "--arg1"]

5 Check File Permissions

Ensure the executable has appropriate permissions, specifically the execute bit (`+x`). You might need to add a `RUN chmod +x /path/to/your-command` step in your Dockerfile if you're copying custom scripts or binaries.

BASH

 $ FROM alpine:latest
COPY my-script.sh /usr/local/bin/my-script.sh
RUN chmod +x /usr/local/bin/my-script.sh
CMD ["my-script.sh"]