GitLab CI "exit code 127" / command not found

Exit code 127 means the shell could not find the command. The binary is not installed in the job image, is under a different name, or is not on PATH.

What this error means

A script step fails immediately with "command not found" and "exit code 127". The same command runs locally because your machine has it installed but the job image does not.

gitlab-ci

$ npm run build
/bin/bash: line 1: npm: command not found
ERROR: Job failed: exit code 127

Common causes

Tool not installed in the image

The job image lacks the binary entirely - a minimal base image without Node, Python, or a CLI the script assumes is present.

Binary not on PATH

The tool is installed but in a directory not on PATH (a local node_modules/.bin, a custom install prefix), so the shell cannot resolve it.

How to fix it

Use an image that has the tool, or install it

.gitlab-ci.yml

build:
  image: node:20      # image already includes node + npm
  script:
    - node --version
    - npm ci
    - npm run build

Put the binary on PATH

For project-local CLIs, call them via npx <tool> or ./node_modules/.bin/<tool>.
For custom installs, export the install directory onto PATH in before_script.
Verify with which <tool> early in the job to fail fast with a clear message.

How to prevent it

Pin a job image that ships the tools the script needs.
Install or vendor required CLIs explicitly in before_script.
Add a quick which/--version check before the main commands.