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

```text
failed to solve: process "/bin/sh -c mycommand --flag" did not complete successfully: exit code: 127
```

## Fix it

1. Read the failing RUN line and spot the command name.
2. 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]`
3. 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.
4. 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 add` the package, and note binaries may live at musl-specific paths.
- `npm`/`pip` installed 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.