What an exit status is
An exit status, or exit code, is a number from 0 to 255 that every command hands back to the shell when it finishes. It reports whether the command worked.
- A script that ignores these numbers carries on after a failure as if nothing happened.
- A script that sets them carelessly tells cron, a monitor or another script that all is well when it is not.
Reading the exit status with $?
0 means success. Anything else means failure. The shell keeps the status of the last command in the special variable $?.
#!/bin/bash
# status.sh: show the exit status of a few commands.
ls /etc/hostname > /dev/null
echo "ls of a file that exists: $?"
ls /no/such/file 2> /dev/null
echo "ls of a missing file: $?"
echo "and \$? now: $?"
root@lab:~/scripts# ./status.sh
ls of a file that exists: 0
ls of a missing file: 2
and $? now: 0
The last line is the trap to remember:
$?is replaced after every command, includingecho.- By the third line it holds the status of the
echobefore it, which worked. - If you need a status later, copy it into a variable straight away, for example
status=$?.
Common exit codes
Zero for success can feel backwards. It makes sense once you see that there is one way to succeed and many ways to fail, and the non-zero values can say which. Some codes are used by the shell itself:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General failure; the most common error code |
| 2 | Wrong usage, such as a bad option or a missing file for ls and grep |
| 126 | The file was found but could not be run, usually no execute permission |
| 127 | Command not found |
| 130 | Stopped with Ctrl+C |
| 128 + n | Killed by signal number n: 143 is SIGTERM (15), 137 is SIGKILL (9) |
You can see several of them at the prompt:
root@lab:~/scripts# nosuchcmd
bash: nosuchcmd: command not found
root@lab:~/scripts# echo $?
127
root@lab:~/scripts# printf 'echo hi\n' > noexec.sh
root@lab:~/scripts# ./noexec.sh
bash: ./noexec.sh: Permission denied
root@lab:~/scripts# echo $?
126
130 is 128 plus 2, the number of SIGINT, the signal Ctrl+C sends. The Linux skill's Processes topic lists the signals.
Checking whether a command worked with if
if does not need [ ]. It runs any command and takes the then branch when that command exits with 0. So the cleanest check is to put the command itself after if:
#!/bin/bash
# copy-config.sh: copy a config file into place, or say why not.
src=$1
if cp "$src" /tmp/app.conf; then
echo "Copied $src"
else
echo "Could not copy $src"
fi
root@lab:~/scripts# ./copy-config.sh app.log
Copied app.log
root@lab:~/scripts# ./copy-config.sh missing.conf
cp: cannot stat 'missing.conf': No such file or directory
Could not copy missing.conf
Use if ! cmd; then to act only on failure. The common mistake is to run the command, then test $? a few lines later, after something else has replaced it:
#!/bin/bash
cp "$1" /tmp/app.conf
echo "Copying $1"
if [ $? -ne 0 ]; then
echo "Copy failed"
fi
root@lab:~/scripts# ./wrong-check.sh missing.conf
cp: cannot stat 'missing.conf': No such file or directory
Copying missing.conf
The if tested the echo, which worked, so the failure was never reported. if cp ...; then cannot go wrong this way.
Short checks with && and ||
For short checks, two operators do the same job on one line:
a && brunsbonly ifasucceeded.a || brunsbonly ifafailed.
mkdir -p /tmp/backups && echo "Backup folder ready"
cd /no/such/dir || echo "Could not enter the folder"
Be careful with a && b || c. It looks like if-then-else, but c also runs when a worked and b failed:
root@lab:~/scripts# true && false || echo "This runs too"
This runs too
When the middle command can fail, write a real if.
Errors belong on stderr
Every process has two output streams:
- stdout (standard output) for its normal output
- stderr (standard error) for messages about problems
Both appear on your terminal, so the difference is easy to miss until the output is piped or captured. Here is a script that writes its error to stdout:
#!/bin/bash
# count-users.sh: print how many lines a file has.
file=$1
if [ ! -r "$file" ]; then
echo "Cannot read $file"
exit 1
fi
wc -l < "$file"
root@lab:~/scripts# n=$(./count-users.sh nope.txt)
root@lab:~/scripts# echo "Users: $n"
Users: Cannot read nope.txt
The error message became the data. Send it to stderr with >&2, which means "send this command's stdout to wherever stderr goes":
echo "count-users: cannot read $file" >&2
root@lab:~/scripts# n=$(./count-users.sh nope.txt)
count-users: cannot read nope.txt
root@lab:~/scripts# echo "Users: $n"
Users:
- Now the message reaches the person at the terminal, and the variable stays empty instead of holding text that looks like a result.
- The rule: results to stdout, everything else to stderr.
- Start each error with the script's name, so that when several scripts run together, as they do under cron, you can tell which one complained.
Stopping with a message: the die pattern
Most checks in a script have the same shape: try something, and if it fails, print an error and stop. The || operator with a group in { } does that in one line:
cd "$dest" || { echo "cannot enter $dest" >&2; exit 1; }
- The spaces inside the braces and the
;before}are required. - Do not use
( )here. Parentheses run their contents in a subshell, a copy of the shell, soexitleaves the subshell and the script keeps going.
When a script has many of these, give the pattern a name. A function called die is the usual choice:
#!/bin/bash
# backup-etc.sh: archive /etc into a backup folder.
die() {
echo "$(basename "$0"): $*" >&2
exit 1
}
dest=${1:-/tmp/backups}
mkdir -p "$dest" || die "cannot create $dest"
cd "$dest" || die "cannot enter $dest"
tar -czf "etc-$(date +%F).tar.gz" /etc 2> /dev/null || die "tar failed"
echo "Saved $dest/etc-$(date +%F).tar.gz"
root@lab:~/scripts# ./backup-etc.sh
Saved /tmp/backups/etc-2026-10-25.tar.gz
root@lab:~/scripts# ./backup-etc.sh /proc/x
mkdir: cannot create directory '/proc/x': No such file or directory
backup-etc.sh: cannot create /proc/x
root@lab:~/scripts# echo $?
1
Each step either works or stops the script with a clear reason. The Functions topic explains why exit inside a function ends the whole script while return would not.
Exiting with the right code
A script's own exit status is set by exit n. Without an exit, a script exits with the status of the last command it ran. That is often an echo, which hides a failure further up:
#!/bin/bash
# cleanup.sh: delete old logs, then report.
rm /var/log/app/*.old
echo "Clean-up finished"
root@lab:~/scripts# ./cleanup.sh
rm: cannot remove '/var/log/app/*.old': No such file or directory
Clean-up finished
root@lab:~/scripts# echo $?
0
Cron, a CI pipeline or a monitoring check would record this run as a success. Check the commands that matter, and exit with a non-zero code when they fail. Some habits:
- Use
exit 1for "it failed" andexit 2for "you called me wrongly", as many standard tools do. - If your script has several distinct failures a caller might act on differently, document the codes in the comment at the top.
- Stay between 0 and 255. Exit codes wrap around, so
exit 256is the same asexit 0, andexit 300gives 44. - Avoid 126, 127 and 128 upwards for your own errors, because they already mean something.
Pipelines and PIPESTATUS
The exit status of a pipeline is the status of its last command. A failure earlier in the pipe is lost:
#!/bin/bash
grep ERROR /no/such/app.log | sort | uniq -c
echo "status: $?"
grep ERROR /no/such/app.log | sort | uniq -c
echo "PIPESTATUS: ${PIPESTATUS[*]}"
root@lab:~/scripts# ./pipes.sh
grep: /no/such/app.log: No such file or directory
status: 0
grep: /no/such/app.log: No such file or directory
PIPESTATUS: 2 0 0
grepfailed with 2, butuniqworked, so the pipeline reported 0.- Bash keeps every command's status from the most recent pipeline in the array
PIPESTATUS, one entry per command, left to right. - Like
$?, it is replaced by the next command, so read it immediately. - The Robust scripts topic shows
set -o pipefail, which makes a pipeline fail when any part of it fails.
Example: grep's three exit codes
grep uses its exit status to say more than "worked" or "failed":
| Status | Meaning |
|---|---|
| 0 | At least one line matched |
| 1 | No line matched; not an error |
| 2 | Something went wrong, such as a missing file or a bad pattern |
root@lab:~/scripts# grep ERROR app.log
ERROR disk full
root@lab:~/scripts# echo $?
0
root@lab:~/scripts# grep WARN app.log
root@lab:~/scripts# echo $?
1
root@lab:~/scripts# grep ERROR nofile.log
grep: nofile.log: No such file or directory
root@lab:~/scripts# echo $?
2
- This is why
if grep -q ERROR app.log; thenreads so naturally:-qprints nothing and only sets the status. - It also shows why "non-zero" does not always mean "broken". For grep, 1 is a normal answer. A script that treats every non-zero status from grep as an error will stop when a log is simply clean.
- Task 2 uses all three outcomes.
Tasks
Task 1: Check that required commands exist
Write need.sh, which takes any number of command names as arguments. For each one that is not installed, it prints need: NAME is not installed to stderr. If any are missing it exits with 1; otherwise it prints All N commands found and exits with 0. Use command -v, which exits with 0 when a command exists. Try it with ./need.sh tar curl jq.
Check your work
#!/bin/bash
# need.sh: check that every command named on the command line is installed.
# Usage: ./need.sh command...
missing=0
for cmd in "$@"; do
if ! command -v "$cmd" > /dev/null; then
echo "need: $cmd is not installed" >&2
missing=$((missing + 1))
fi
done
if [ "$missing" -gt 0 ]; then
exit 1
fi
echo "All $# commands found"
root@lab:~/scripts# ./need.sh tar curl jq
need: curl is not installed
need: jq is not installed
root@lab:~/scripts# echo $?
1
root@lab:~/scripts# ./need.sh tar grep
All 2 commands found
root@lab:~/scripts# echo $?
0
The base Ubuntu image has no curl or jq, so your output should match. A common mistake is to exit 1 inside the loop at the first missing command, which hides the others; checking them all and failing at the end tells the user everything to install in one go. Another is to forget > /dev/null, which prints the path of every command that was found.
Task 2: A log check a monitor can use
Write log-check.sh FILE, which looks for lines containing ERROR:
- No ERROR lines: print
FILE: no errorsand exit 0. - ERROR lines found: print
FILE: N ERROR linesand exit 1. - The file cannot be read, or no argument given: print a message to stderr and exit 2.
Use the exit status of grep -c, which prints the number of matching lines. Make two test files: app.log with two ERROR lines and clean.log with none.
Check your work
#!/bin/bash
# log-check.sh: report ERROR lines in a log file.
# Exit 0: no errors. Exit 1: errors found. Exit 2: the file could not be read.
# Usage: ./log-check.sh file
file=$1
if [ $# -ne 1 ]; then
echo "Usage: $0 file" >&2
exit 2
fi
count=$(grep -c ERROR "$file")
status=$?
case $status in
0)
echo "$file: $count ERROR lines"
exit 1
;;
1)
echo "$file: no errors"
exit 0
;;
*)
echo "log-check: could not read $file" >&2
exit 2
;;
esac
root@lab:~/scripts# printf 'INFO start\nERROR disk full\nERROR disk full\nINFO stop\n' > app.log
root@lab:~/scripts# printf 'INFO start\nINFO stop\n' > clean.log
root@lab:~/scripts# ./log-check.sh app.log; echo "exit: $?"
app.log: 2 ERROR lines
exit: 1
root@lab:~/scripts# ./log-check.sh clean.log; echo "exit: $?"
clean.log: no errors
exit: 0
root@lab:~/scripts# ./log-check.sh nope.log; echo "exit: $?"
grep: nope.log: No such file or directory
log-check: could not read nope.log
exit: 2
The exit status of count=$(grep ...) is grep's status, so status=$? on the very next line catches it. The likely mistake is putting an echo between the two lines, after which $? is 0 every time. Note that here "errors found" is exit 1, not 0: the script's job is to answer "is this log healthy", and a monitor treats non-zero as "not healthy".
Quiz
1. What does this script print?
#!/bin/bash
ls /no/such/dir 2> /dev/null
echo "first: $?"
echo "second: $?"
false && echo "A" || echo "B"
Show answer
first: 2
second: 0
B
ls fails with 2. The first echo succeeds, so the second one sees 0. false fails, so echo "A" is skipped and || echo "B" runs.
2. A script on a server runs from cron every night. It copies files with rsync and its last line is echo "Sync done at $(date)". Last week rsync failed for three nights and nobody was told, even though cron is set up to alert on a non-zero exit. Why, and how do you fix it?
Show answer
A script exits with the status of its last command, and the echo always works, so every run exited with 0. Check rsync and exit non-zero when it fails, for example rsync ... || { echo "sync: rsync failed" >&2; exit 1; }, before the final echo.
3. You run deploy and then echo $?, and see 127. A colleague's run of the same script shows 126. What does each code tell you?
Show answer
127 means the command was not found: it is not in PATH, or the name is misspelled. 126 means the file was found but could not be run, usually because it lacks the execute permission. The fixes are different: check PATH for the first, chmod +x for the second.
4. curl -s https://example.com/data.csv | grep -c ok prints 0, and echo $? prints 1. How do you find out whether curl itself worked?
Show answer
$? holds the status of grep, the last command in the pipeline; 1 just means no line matched. Check ${PIPESTATUS[0]} immediately after the pipeline to get curl's status, or turn on set -o pipefail so any failing part of the pipe makes the whole pipeline fail.