GitHub Actions "Process completed with exit code 2" - Usage/Build Error

A run step exited with code 2. Many tools reserve exit 2 for a usage or misuse error (bad flags), and make/grep/shell use it for build or syntax failures. The real cause is the tool's output above the exit line.

What this error means

A step ends with "Process completed with exit code 2" and the job fails. The exit code itself is generic - the actual error (bad argument, failed build target, shell syntax) is earlier in the log.

make: *** [Makefile:14: build] Error 2
Error: Process completed with exit code 2.

Common causes

Tool-specific misuse or build failure

Exit 2 commonly signals a usage error (unknown flag), a make target failure propagating a sub-command's status, or grep finding no match in some modes.

Shell syntax error

A bash syntax error (unmatched quote, bad redirection) exits 2, failing the step before the intended command even runs.

How to fix it

Read the error above the exit line

1. Scroll up to the first real error - a usage message, a failed make target, or a syntax error.
2. Reproduce the exact command locally to confirm the cause.
3. Fix the underlying issue (correct the flag, fix the build, fix the shell syntax).

Isolate the failing command

Split a combined step so the failing command is obvious, and validate shell scripts before running them.

- name: Lint shell
  run: bash -n ./scripts/deploy.sh   # catches syntax errors (exit 2) early
- name: Build
  run: make build

How to prevent it

• Split combined steps so a code-2 failure points at one command.
• Validate shell scripts with bash -n in CI.
• Treat exit 2 as "tool usage/build error", then read the log above it.

Related guides