failed to solve: process "/bin/sh -c mycommand --flag" did not complete successfully: exit code: 127
Fixes docker build RUN steps failing with exit code 127 (command not found). Use when the build fails because a binary is missing from PATH, not installed yet, or the shell cannot find it. Not for exit code 100 (apt failure) or nonzero codes from commands that exist but errored.
TL;DR: The command in your RUN line does not exist in the image. Either install the package that provides it earlier in the Dockerfile, fix the typo in the command name, or use the full path. Exit code 127 is the shell's 'command not found', so the fix is always about making the binary present.
The error
failed to solve: process "/bin/sh -c mycommand --flag" did not complete successfully: exit code: 127Fix it
- Read the failing RUN line and spot the command name.
- Check whether the package providing it is installed in an EARLIER layer. If not, add the install before the failing line:
RUN apt-get update && apt-get install -y [package]
- If it should be installed, check for typos and PATH issues:
RUN which mycommand || ls /usr/local/bin Expected: reveals the typo or the wrong directory.
- Rebuild.
When this applies
- Any RUN step failing with exit code 127
- Multistage builds where a tool exists in the builder stage but not the final stage
When this does NOT apply
- Exit code 100/1 from a command that ran (the command exists; its arguments or environment are wrong)
- "executable file not found in $PATH" at container START (ENTRYPOINT problem, separate skill)
Versions
All Docker versions. The phrasing differs slightly between classic builder ("returned a non-zero code: 127") and BuildKit ("did not complete successfully").
Why it happens
Each RUN executes in a fresh shell in the image's current filesystem state. Tools installed via a package manager in a previous layer are available, but anything you assumed was present (curl, git, python) often is not in slim images.
Edge cases
- Alpine images: many Debian-isms are missing;
apk addthe package, and note binaries may live at musl-specific paths. npm/pipinstalled via a version manager (nvm, pyenv) are not on PATH for non-interactive RUN shells; use the full path or set ENV PATH.- Windows containers: 127 equivalents surface as different error codes; this skill is Linux-focused.
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.