GitHub Actions "/usr/bin/bash: line N: command not found"

By Kaveh Alemi·Latchkey

A run step invoked a binary the runner cannot resolve. Bash searches PATH, finds nothing, and exits the step with code 127. The shell itself is fine; the named command is missing or misspelled.

What this error means

A run step fails immediately on the line that calls a CLI tool, printing the tool name followed by "command not found".

github-actions

/usr/bin/bash: line 2: pnpm: command not found
##[error]Process completed with exit code 127.

Diagnose it: is the job queued, or is the runner gone?

A job that never starts and a job whose runner disappeared mid-run look similar in the UI and have opposite causes. The first is a labelling or capacity problem, the second is the runner being killed, usually by memory pressure or a spot reclaim.

.github/workflows/ci.yml

- name: Runner facts
  run: |
    echo "runner name: $RUNNER_NAME"
    echo "os/arch:     $RUNNER_OS/$RUNNER_ARCH"
    nproc; free -h; df -h /
    echo "labels this job asked for: ${{ toJSON(job) }}"

Common causes

Tool was never installed on the runner

The image does not ship the binary, and no setup-* step (or install command) ran before the step that uses it.

Tool installed but not added to PATH

An installer placed the binary in a custom directory that was not appended to GITHUB_PATH, so later steps cannot see it.

Typo in the command name

A misspelled binary (for example "pyhton" or "yanr") never matches anything on PATH.

How to fix it

Install the tool before you use it

Add the relevant setup action or install command as an earlier step in the same job.
Confirm the version line runs successfully before the failing step.
Re-run; the binary now resolves on PATH.

.github/workflows/ci.yml

- uses: pnpm/action-setup@v4
  with:
    version: 9
- run: pnpm --version
- run: pnpm install --frozen-lockfile

Add a custom install dir to PATH

Append the install directory to GITHUB_PATH in the install step.
PATH changes via GITHUB_PATH apply to subsequent steps, not the current one.
Re-run and verify the command resolves.

install + GITHUB_PATH

- run: |
    curl -sSL https://example.com/install.sh | sh -s -- --bin-dir "${HOME}/.local/bin"
    echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
- run: mytool --version

The failures that are not your workflow

Exit 137 is the kernel out-of-memory killer, not an application error. Check free -h above against your peak usage.
Disk exhaustion presents as unrelated write errors deep in a build. GitHub-hosted runners ship roughly 14 GB of free space, which a Docker-heavy job can exhaust.
A lost connection to the server on a self-hosted runner is usually the host being reclaimed or rebooted, not a network fault in your job.
A job that starts and immediately fails with no step output normally failed during runner setup, before your workflow ran at all.

How to prevent it

Pin a setup action for every toolchain your workflow depends on.
Print "tool --version" right after install to fail fast with a clear message.

Frequently asked questions

What causes GitHub Actions "/usr/bin/bash: line N: command not found"?

There are 3 common causes: tool was never installed on the runner, tool installed but not added to path, and typo in the command name. The image does not ship the binary, and no setup-* step (or install command) ran before the step that uses it.

How do I fix GitHub Actions "/usr/bin/bash: line N: command not found"?

There are 2 fixes depending on which cause you have: install the tool before you use it and add a custom install dir to path. Work through them in order, since the first is the most common.

What does GitHub Actions "/usr/bin/bash: line N: command not found" actually mean?