Skip to content
Tutorials Center
My learning

Topics

Lesson 43 of 95 ยท Shell Scripting

Exit Codes, set -e and Error Handling

Learn Bash exit status, set -euo pipefail and its gotchas, trap ERR and EXIT, cleanup with mktemp -d, errors to stderr, idempotent scripts and retry loops.

Every command you run ends with a number between 0 and 255 called its exit status. Zero means success; anything else means some kind of failure. Shell scripts are built on this one idea: if, &&, || and while all ask "did that command succeed?". A script that ignores exit statuses will happily continue after a failed cd and delete the wrong folder.

This lesson shows how to read exit statuses, how to make a script stop when something goes wrong with set -euo pipefail (and the surprising places where it does not), how to clean up after yourself with trap and mktemp -d, and how to write scripts you can safely run twice. It builds on Writing Your First Script and Conditionals.

Exit status basics

The status of the last command is in the special variable $?. Read it immediately: the next command overwrites it.

Bash Reading $? and the meaning of common codes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Memorise these conventions:

Status Usual meaning
0 Success
1 General failure
2 Misuse of the command (bad options). grep also uses 2 for real errors, 1 for "no match"
126 Found, but cannot be executed (permissions)
127 Command not found
128 + n Killed by signal n (130 = Ctrl-C/SIGINT, 137 = SIGKILL, 143 = SIGTERM)

Statuses wrap around at 256, which is why exit 300 gives 44. Pick codes from 1 to 125 for your own scripts, and document them if callers depend on them.

Statuses drive control flow

An if does not need [ ]; it accepts any command and checks its status. This is why if grep -q pattern file; then is the idiomatic way to test for a match.

Bash if, &&, || and ! all use exit status

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

A function's status is the status of its last command, or the number given to return. A script's status is the status of its last command, or the number given to exit. If you end a script with an echo, it exits 0 even when earlier steps failed. That is exactly the gap that set -e tries to close.

Failing loudly: errors go to stderr

Write error messages to standard error with >&2, and exit with a non-zero code. Callers can then separate results (stdout) from diagnostics (stderr), and cmd > out.txt does not bury the error inside the output file. A tiny helper keeps this tidy:

Bash A die helper that writes to stderr

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

set -e, set -u and set -o pipefail

Three options turn Bash from "keep going no matter what" into "fail fast". They are usually written together, often as set -euo pipefail near the top of a script:

Option Effect
set -e (errexit) Exit when a simple command fails (with exceptions, see below)
set -u (nounset) Treat an unset variable as an error instead of an empty string
set -o pipefail A pipeline fails if any stage fails, not just the last one
Bash Without and with set -euo pipefail

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

set -u is the cheapest bug catcher of the three: a misspelled variable in rm -rf "$build_dir/" becomes an immediate error instead of rm -rf /. When you do want to read a variable that may be unset, give it a default: ${name:-}.

The gotchas of set -e

set -e is useful but famously full of exceptions. It does not exit when the failing command is:

  • part of an if, while or until condition;
  • anything but the last command in an && or || list;
  • negated with !;
  • inside a function or subshell that is itself used in one of those contexts. Inside such a context, set -e is ignored for the whole called function.
Bash Where set -e does not stop the script

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Case 4 is the nastiest: if you call a function from an if (or ||), every set -e inside it is switched off, so a function that "stops on first error" quietly stops doing so. The practical advice:

  • Treat set -e as a safety net, not as your error handling. For the steps that really matter, check explicitly: cd "$dir" || die 1 "cannot enter $dir".
  • Handle expected failures on purpose. To allow a command to fail, write cmd || true, or test it in an if.
  • local x=$(cmd) hides the status of cmd (the status you see is the one of local). Declare first, assign second: local x; x=$(cmd).
  • Arithmetic like (( count++ )) returns status 1 when the result is 0, so with set -e it kills the script the first time count is 0. Use count=$((count + 1)) instead.
Bash Two classic traps: local x=$(...) and (( i++ )) (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Both scripts finish with status 1, and the second one stops silently, with no error message at all. That silence is typical of set -e: it exits, but it does not tell you why. Combine it with an ERR trap (next sections) to get a message.

Cleanup with trap and mktemp

Scripts that create temporary files should remove them on every exit path: normal end, error, and Ctrl-C. The tools are mktemp -d (a unique private directory) and trap ... EXIT (a handler Bash runs when the shell exits for any reason).

TEXT
   script starts
        |
        v
  tmp=$(mktemp -d)  ----> trap 'rm -rf "$tmp"' EXIT
        |
        v
   do work ... (may fail, may be interrupted)
        |
        v
   shell exits  ===>  EXIT trap runs  ===>  temp directory removed
Bash mktemp -d plus an EXIT trap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The trap ran in both cases, and the script kept the exit status of the failure. Remember that SIGKILL (kill -9) cannot be trapped, so a killed script cannot clean up; that is one reason to prefer SIGTERM for stopping things. Signals get their own lesson: Signals and trap.

trap ERR: say where it failed

An ERR trap runs when a command fails (under the same rules as set -e). Combined with the LINENO variable and set -E (so the trap is inherited by functions), it turns silent failures into useful messages.

Bash An ERR trap that reports the failing line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

$BASH_COMMAND holds the command that was running. The trap fires, prints the message, and then set -e ends the script with the original status.

Defensive patterns

A handful of habits prevent most disasters:

  • Check cd: cd "$dir" || exit 1. Otherwise the next rm * runs in the wrong folder.
  • Guard dangerous variables: rm -rf "${build_dir:?}/" aborts with an error if build_dir is unset or empty.
  • Quote everything (Quoting), and use -- before file names that may start with a dash.
  • Test inputs first: check that files exist and arguments are valid before changing anything.
  • Prefer atomic updates: write to a temporary file in the same directory, then mv it over the target. Readers never see a half-written file.
Bash The ${var:?} guard and cd checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Idempotent scripts

A script is idempotent when running it twice gives the same result as running it once. That makes it safe to re-run after a failure halfway, which is exactly what you will do. The usual recipe is to describe the desired state and skip steps that are already done:

  • mkdir -p dir instead of mkdir dir (no error if it exists);
  • rm -f file instead of rm file;
  • ln -sfn target link to replace a symlink;
  • append a line to a config file only if grep -qxF does not find it.
Bash Running the same script twice

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Retry loops

Some failures are temporary (a busy server, a file not yet written). A retry loop tries a few times with a growing pause, and gives up with a clear error.

Bash A retry helper with a limit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

The until "$@" form runs the command given as arguments and loops while it fails. Because until is a condition context, set -e does not fire for the failing attempts, which is what you want here.

When to use what

  • set -euo pipefail at the top of every script that is not purely interactive: yes, as a net. Know its holes.
  • Explicit || die checks for the commands whose failure you must handle in a specific way.
  • trap ... EXIT for cleanup, trap ... ERR (with set -E) for diagnostics.
  • If failures are normal for a command (like grep finding nothing), handle them with if or || true, so the script's flow stays readable.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does echo $? print right after grep -q needle file.txt when the file does not contain needle?

    grep exits 0 when it finds a match, 1 when it finds none, and 2 when an error occurs. The -q option only hides the output, not the status.
  2. 2. Which statement about set -e is correct?

    Commands used as an if/while/until condition, in an and/or list, or negated with ! are exempt. Without pipefail only the last stage of a pipeline counts, and set -e is ignored inside a function called in such a context.
  3. 3. What does set -o pipefail change?

    By default a pipeline's status is that of its last command. With pipefail it is the status of the rightmost command that failed, or zero if all succeeded.
  4. 4. Why is local out=$(some_command) a problem when you use set -e?

    The assignment and the local builtin are one command, and its status is local's (almost always 0). Write local out on one line and out=$(some_command) on the next to keep the real status.
  5. 5. Which signal can NOT be caught by a trap, so an EXIT trap will not run for it?

    SIGKILL (kill -9) is delivered by the kernel and cannot be caught, blocked or ignored. INT, TERM and HUP can be trapped, and the EXIT trap runs after them.

Summary

  • Every command returns a status: 0 is success, non-zero is failure; 126, 127 and 128+n have fixed meanings.
  • if, &&, ||, while and until test statuses; use return in functions and exit in scripts.
  • Send error messages to stderr and exit with a non-zero code; use 2 for usage errors.
  • set -euo pipefail is a good safety net, but set -e is skipped in conditions, and-or lists and functions called from them. Check critical steps explicitly.
  • Clean up with mktemp -d and trap ... EXIT; get diagnostics with set -E and trap ... ERR.
  • Write idempotent scripts (mkdir -p, rm -f, ln -sfn, check before append) and wrap flaky steps in a bounded retry loop.

Next: Signals and trap