Bash exit codes 0-255: what they mean and how to write the handler

Question

$? holds the exit code of the last command that ran. You've seen it. You've probably checked it. What you might not have is a reliable reference for what each value actually means — and more importantly, what to do about it in your script.

Here's the most common codes with the detail that's usually missing from quick-reference tables.

---

0 — Success

The command exited cleanly. Zero is the only value that means success. Everything else is some form of failure or interruption.

---

1 — General error

This is the catch-all. A lot of programs use 1 to signal "something went wrong but I'm not going to be more specific." When you see 1, you need to look at the command's own output or error messages to find out what actually failed.

---

2 — Misuse of shell built-in

You called a bash built-in with wrong arguments. Common cause: if [ $var = ] with a missing right-hand operand. The [ command exits 2 when the syntax is wrong.

---

126 — Command found, not executable

The binary exists but can't be run. Most common cause: missing execute permission. Fix: chmod +x yourscript.sh. Worth noting: this is different from 127. The system found the file — it just can't execute it.

---

127 — Command not found

The binary doesn't exist or isn't in PATH. Most common causes: typo in command name, package not installed, or PATH issue in cron (see the cron job post above). When you see 127 in a cron job context, check PATH first.

---

130 — Killed with Ctrl-C (SIGINT)

The formula is 128 + signal number. SIGINT = signal 2. 128 + 2 = 130. If your script sees 130 from a subprocess, someone hit Ctrl-C (or the process received SIGINT programmatically).

---

137 — Killed with SIGKILL

128 + 9 (SIGKILL). This is the OOM killer. When Linux runs out of memory and needs to reclaim it fast, SIGKILL is what it uses. If your script exits 137 unexpectedly on a server, check available memory — free -h and dmesg | grep -i kill.

---

139 — Segmentation fault

The process tried to access memory it wasn't allowed to access. In a bash context, this usually means a compiled binary your script called has a bug. You're not going to fix the segfault from bash — but you can detect it and handle it cleanly.

---

143 — Killed with SIGTERM

128 + 15 (SIGTERM). This is the polite kill — what kill PID sends by default, and what systemd sends when stopping a service. Unlike SIGKILL, SIGTERM can be caught and handled.

---

The error handler problem

Knowing what a code means is step one. Writing a handler that does something useful with it is step two. Most bash error handling I see in the wild looks like this:

if [ $? -ne 0 ]; then
  echo "error"
  exit 1
fi

Which logs nothing meaningful and loses the original exit code. A better pattern:

if [ $? -eq 127 ]; then
  echo "ERROR: command not found — check PATH or installation" >&2
  exit 127
fi

Log to stderr, preserve the original exit code, be explicit about what went wrong.

---

Free tool that generates these handlers

I built [Bash Exit Code Lookup][(https://bashsnippets.xyz/tools/bash-exit-code-lookup.html)]1 to remove the "Google it, then write the handler by hand" step. You type a code (or click one of the common ones), pick a handler style — if/else block, case statement, or inline || fallback — and copy the generated handler directly into your script.

All codes 0-255 are in there. Free, no login.

→ https://bashsnippets.xyz/tools/bash-exit-code-lookup.html