Docker "executor failed running [/bin/sh -c ...]: exit code: N" in CI

A RUN step exited non-zero and Docker reported it with the older executor failed running [...]: exit code: N wording. The real failure is in the command output just above this line.

What this error means

A docker build aborts with executor failed running [/bin/sh -c <cmd>]: exit code: N (or The command '/bin/sh -c <cmd>' returned a non-zero code: N). The wrapper names the failing command; the actual error is printed in the lines above it.

Step 6/9 : RUN make build
 ---> Running in 3f2a...
make: *** [build] Error 2
The command '/bin/sh -c make build' returned a non-zero code: 2
# BuildKit phrasing: executor failed running [/bin/sh -c make build]: exit code: 2

Common causes

The command inside RUN genuinely failed

A compile error, a failing test, a non-zero make/script, or a bad flag makes the command exit with code N. A non-zero RUN is, by design, a build failure.

A required tool or file is missing in that layer

The command depends on a binary, file, or environment variable not present in the image at that step, so it errors out rather than crashing.

Exit code N maps to a specific signal/condition

Codes carry meaning: 127 is "command not found", 126 is "not executable", 137 is SIGKILL/OOM. The number narrows the cause.

How to fix it

Read the output above the wrapper line

1. The executor failed running line only names the command - scroll up to the real error it printed.
2. Re-run with --progress=plain so the full, uncollapsed command output is visible.
3. Map the exit code: 127 = not found, 126 = not executable, 137 = OOM/SIGKILL, others = the command’s own error.

Reproduce the failing command in the base image

Run the exact command in an interactive container to debug it directly.

docker run --rm -it <base-image> sh -c 'make build; echo exit=$?'

How to prevent it

• Use set -euo pipefail in multi-command RUN blocks so failures surface clearly.
• Keep one logical action per RUN where practical so the failing step is obvious.
• Pin a Docker/BuildKit version so the error phrasing is consistent across runners.

Related guides