Exit Code 127 Explained: Command Not Found in CI
Exit code 127 is the shell saying "I could not find that command" - the executable is not installed, not on PATH, or misspelled.
When a CI step ends with 127, the command never actually ran. The shell looked for it, failed to locate it, and gave up before any of the program’s own logic executed.
What 127 means
The shell returns 127 when it cannot resolve a command name to an executable. It is distinct from "the command ran and failed" - nothing ran at all. You will usually see a command not found message alongside it.
Common causes in CI
- A tool that is installed locally but not on the runner’s image.
- A tool installed into a directory that is not on PATH.
- A typo in the command name or a wrong binary name.
- A previous setup step failed silently, so the tool was never installed.
How to fix it
Confirm the tool is installed in the job (add an explicit install step), and confirm it is on PATH (which <tool> or command -v <tool>). On ephemeral runners, nothing persists between jobs, so every tool a step needs must be installed within that job or baked into the runner image.
- run: command -v jq || sudo apt-get install -y jq
- run: jq --version127 vs 126
Do not confuse them: 127 means the command was not found, while 126 means it was found but is not executable (wrong permissions or a broken interpreter line). Different fixes - install/PATH for 127, chmod/shebang for 126.
Key takeaways
- Exit 127 = command not found; nothing actually ran.
- Causes: tool not installed, not on PATH, or misspelled.
- On ephemeral runners, install every needed tool inside the job or bake it in.
- 127 (not found) is different from 126 (found but not executable).