Docker "returned a non-zero code: 1" on a RUN step in CI

By Kaveh Alemi·Latchkey

A RUN command exited non-zero, so the build stopped. The error is just the messenger; the real failure is in the command output above it (a failed install, compile, or script).

What this error means

A build fails on a RUN line with The command /bin/sh -c <cmd> returned a non-zero code: 1 (or did not complete successfully: exit code: 1 under BuildKit). The actual error is in the preceding output.

ERROR: process "/bin/sh -c npm ci && npm run build" did not complete successfully: exit code: 1
The command '/bin/sh -c npm ci && npm run build' returned a non-zero code: 1

Common causes

The command genuinely failed

A compile error, failing test, missing dependency, or bad script inside the RUN exited non-zero.

Network/registry hiccup during the RUN

A package download in the RUN hit a transient failure, which is flaky and often passes on retry.

Silent failure masked by piping

A pipeline without pipefail hid the failing command and surfaced a confusing exit code.

How to fix it

Read and reproduce the real error

1. Scroll above the non-zero line to the actual command output.
2. Reproduce the RUN locally with the same base image to debug it.

docker build --progress=plain --no-cache -t app .

Make failures explicit and deterministic

1. Use set -euxo pipefail in shell RUN steps so the failing command is obvious.
2. Pin dependency versions so installs are reproducible.

RUN set -euxo pipefail; \
    npm ci && npm run build

How to prevent it

• Use set -euo pipefail in RUN steps and pin dependency versions. If a RUN fails only on a flaky package download, self-healing managed runners like Latchkey auto-retry that transient failure rather than failing the whole build.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation