← Back to Home

Bash set -e: 9 silent failures with exit code 0

Bashshell scriptingdebugging

Last week a release script finished with deploy finished on the last line and echo $? printed 0. Then I looked at the artifact directory: not a single file had been updated. The log had the evidence right there — cd had printed No such file or directory and cp had printed cannot stat. Two error messages, zero effect on the exit code, and a script that walked all the way to the end and reported success.

That is not a bug in set -e. It is my misreading of its boundary. set -e does not mean "exit when any command fails"; it means "exit when a command fails, unless it sits in one of these positions": a condition test, a || or && list, a non-final pipeline segment, something inverted with !. And if a function runs in a context where -e is being ignored, the whole function body loses the protection.

This post is the nine silent failures I hit in that round. I ran each one on the bash 5.3.15(1)-release that ships with Git Bash (build target x86_64-pc-cygwin, system MINGW64_NT-10.0-26300), and every claim comes with an exit code or a disk-level result you can rerun. It belongs to the layer about the gap between "the exit code" and "what actually happened". Earlier posts covered the process layer (seven silent subprocess failures), the control-flow layer (asyncio cancellation) and the parsing layer (eight csv boundaries). This one is the shell layer: the script says it succeeded, but it never did the work.

No affiliate links in this post, and no product pages.

TL;DR: set -e is inert in five positions (an if/while condition, a || or && list, an inverted ! command, a non-final pipeline segment), and a function used as a condition loses the protection for its entire body. local x=$(cmd) returns the status of local itself, so the failure disappears. A pipeline reports the rightmost command only, and pipefail is off by default. $? gets overwritten by local, if and echo. Command substitution does not inherit set -e unless shopt -s inherit_errexit (bash 4.4+). "$D/" with an empty D is just /, and quoting will not save you. A while loop on the right side of a pipe runs in a subshell, so the counter resets to 0. An unquoted here-doc delimiter expands $ and backticks at write time, and an unterminated here-doc produces a warning while still exiting 0.

// FLOW_01From "the script said it worked" to "it worked"4 NODES01STEP_01Reproduce an exit-0 false success02STEP_02check each of the nine exemption contexts03STEP_03add pipefail and inherit_errexit04STEP_04put a trap ERR safety net and verify againEND_OF_FLOW
From "the script said it worked" to "it worked" · diagram drawn from this article
GitBash
Technologies referenced · icons from Simple Icons (CC0)

1. Start with an exit-0 "success"

First, shrink the symptom to a script you can rerun. This is the skeleton I had, with the path changed to /opt/app/release; the line numbers and the error text are exactly what the machine printed:

#!/usr/bin/env bash
set -e
DIR=/opt/app/release
cd "$DIR" || true
note() { local out=$(cp missing.txt "$DIR/"); echo "copy done"; }
note
count=$(ls -1 "$DIR" 2>/dev/null | wc -l)
if [ "$count" -gt 0 ]; then echo "artifact ok"; fi
n=0
printf 'a\nb\n' | while read -r line; do n=$((n + 1)); done
echo "processed $n lines"
echo "deploy finished"

Here is what it printed, with neither $DIR nor missing.txt existing:

deploy-bad.sh: line 4: cd: /opt/app/release: No such file or directory
cp: cannot stat 'missing.txt': No such file or directory
copy done
processed 0 lines
deploy finished

Three facts that contradict each other: both errors were printed; copy done was printed after cp had already failed; and the script exited 0 (echo $? gave 0), with bash -n agreeing at 0.

Each failure was swallowed by a different mechanism. cd ... || true is an explicit || list. local out=$(cp ...) is local eating the status of the command substitution. printf | while read puts the counter in a subshell. Take them one at a time.

2. Failure one: set -e has five exemptions

The bash manual is explicit in . The original sentence:

The shell does not exit if the command that fails is part of the command list
immediately following a while or until reserved word, part of the test in an if
statement, part of any command executed in a && or || list except the command
following the final && or ||, any command in a pipeline but the last (subject to
the state of the pipefail shell option), or if the command's return status is
being inverted with !.

Translated into a rule you can apply: whenever the failing command stands in a "condition position", set -e looks away. Six variations, five of which exit 0:

Where the failing command sitsWhat happenedScript exit code
On its own lineexited immediately1
As an if conditionsurvived and kept going0
Left side of an or-listsurvived0
Left side of an and-listsurvived0
Inverted with !survived0
As a while conditionsurvived0

The first row is the baseline: a bare false does stop the script. The trouble is that in real scripts a failure almost never stands bare. It sits inside an if test, behind a || fallback, or at the head of a pipeline that ends in tail or grep -q. Five of the six positions are inert, 5/6, or 83%.

There is a follow-up clause immediately after that paragraph, and it is the root of the next failure:

If a compound command or shell function executes in a context where -e is being
ignored, none of the commands executed within the compound command or function
body will be affected by the -e setting, even if -e is set and a command returns
a failure status.

3. Failure two: a function used as a condition loses everything

The common assumption is that set -e still applies inside a function called as an if condition. It does not:

set -e
f() { false; echo "this line ran anyway"; }
if f; then echo "then branch"; fi

Both lines printed, and the function returned 0, because its last command (echo) succeeded. The if sees the function's overall status, not the failed command in the middle. That false neither stopped the function nor changed its return value.

BashFAQ/105 describes it this way: "As soon as a function is used as a conditional (in a list or with a conditional test or loop) set -e stops being applied within the function." It adds that this not only lets code keep running, it can also change the function's return status.

There are only two ways out: never put a function that relies on set -e into a condition, or check each step inside the function. The second is more reliable:

set -e
f() {
  false || return 1
  echo "only reached if the step above succeeded"
}
if f; then echo "then branch"; fi

4. Failure three: local x=$(cmd) eats the status

This was the hardest one to find in this round. Two forms differ by a single semicolon and behave completely differently:

# A: the failure is swallowed, the script continues, exit code 0
set -e
f() { local out=$(false); echo "A continues"; }
f

# B: the whole script exits 1
set -e
f() { local out; out=$(false); echo "B should not print"; }
f

A printed "A continues" and exited 0. B printed nothing and the script exited 1. The difference is local: when it takes an assignment as an argument, the return status is that of local, not of the command substitution. The manual's wording for local is "The return status is zero unless local is used outside a function, an invalid name is supplied, or name is a readonly variable." None of those three conditions mentions the command being assigned.

BashFAQ/105 groups this with export, declare and typeset: "the exit status of local masks it (the assignment to the variable succeeds, so local returns status 0)".

So the checklist needs one mechanical step: search the file for lines where local is followed directly by =. Split them in two, or add an explicit || return 1.

5. Failure four: a pipeline only reports its rightmost command

The manual's Pipelines node says: "The exit status of a pipeline is the exit status of the last command in the pipeline, unless the pipefail option is enabled." And the default for pipefail, from the same manual, is "This option is disabled by default."

Four measurements:

ScenarioExit codeWhy
Left segment fails, right segment succeeds0only the last one counts
Same, with set -e on0set -e cannot help; the pipeline is 0
Same, with pipefail on1the rightmost non-zero wins
Left segment exits 3, right exits 00the 3 on the left is invisible

Row three is the point: set -e and pipefail answer different questions. The first decides whether a failure stops the script; the second decides what the pipeline counts as. With set -e alone, a failure on the left of a pipe is invisible — which is the most common trap in tar czf - dir | gzip -d style commands.

pipefail has a cost. Once the left side counts, commands that close the pipe early start producing false failures:

set -eo pipefail
seq 1 200000 | head -n 1

On this machine that printed 1 and then exited 141 (128 + 13, SIGPIPE). The same line without pipefail exits 0. If you need this shape, mark it explicitly with || true, or avoid closing the pipe early.

6. Failure five: $? has already been overwritten

$? holds the status of "the previous command", and local, if and echo are all commands:

false; local x; echo "reads $?"
false; if true; then :; fi; echo "reads $?"

Both lines printed 0. The 1 from false was gone: local x succeeded (status 0) and the if statement succeeded as a whole (status 0). The only reliable form is to capture it immediately:

false
rc=$?
echo "rc=$rc"    # prints 1

Combined with the previous failure this is nasty: local swallows the failure, then $? is read, and the value is always 0 — so code that looks like it is checking results is doing nothing at all.

7. Failure six: command substitution does not inherit set -e

$(...) runs in a subshell, and the subshell does not inherit set -e unless you turn that on:

set -e
x=$(false; echo inner)
echo "x=$x"     # x=inner, script exit code 0

Measured output was x=inner with exit code 0: the first half of the substitution failed, the second half succeeded, and the outside world saw nothing. The behaviour flips once you enable the option that bash 4.4 introduced:

set -e
shopt -s inherit_errexit
x=$(false; echo inner)   # exits 1 here; the echo never runs

The measured exit code went from 0 to 1. BashFAQ/105 puts it as "Subshells from command substitution unset set -e, however (unless inherit_errexit is set with Bash 4.4)". I also checked the default on this machine: shopt -p inherit_errexit prints shopt -u inherit_errexit, so it is off.

The same node of the manual documents a second effect: "replacing the command substitution with the standard output of the command, with any trailing newlines deleted". Measured, x=$(printf 'abc\n\n\n') leaves ${#x} at 3 — three newlines gone. Every validation that compares the length of $(cat file) is therefore wrong by construction; compare bytes instead (cmp, sha256sum, or $(< file) plus an explicit newline).

8. Failure seven: quoting does not stop an empty variable from becoming a root path

Quoting fixes word splitting. It does nothing about a variable that is empty:

D=""
printf 'quoted:   [%s]\n' "$D/"
printf 'unquoted: [%s]\n' $D/

Both print [/]. "$D/" expands to the empty string plus a slash, and that is a root path. In rm -rf "$DIR/", an empty DIR makes the target /. This post does not run that command; it prints the expansion with printf instead, and nobody should verify it on their own machine.

Three guards, measured:

FormResult
: "${D:?D is empty}"prints bash: line 1: D: D is empty and exits non-zero
[ -z "${D:-}" ] plus explicit branchcontrollable, the one I use
${D%/} to strip a trailing slashstill empty; solves nothing

The distinction matters: ${D:?} errors on empty, while ${D%/} only removes one trailing slash. The second is often mistaken for a guard while guarding nothing.

9. Failure eight: a while loop on the right of a pipe is a subshell

This one is famous, but it usually shows up as "the counter is 0" rather than as an error:

n=0
printf 'a\nb\nc\n' | while read -r line; do n=$((n + 1)); done
echo "n=$n"

Measured n=0. The manual's Pipelines node explains: "Each command in a multi-command pipeline, where pipes are created, is executed in its own subshell". The n inside the loop belongs to the subshell; the parent's n never moved.

All three alternatives measured n=3:

# 1) process substitution keeps the loop in the current shell
n=0
while read -r line; do n=$((n + 1)); done < <(printf 'a\nb\nc\n')
echo "n=$n"

# 2) lastpipe, available since bash 4.2 (job control must be off)
shopt -s lastpipe
n=0
printf 'a\nb\nc\n' | while read -r line; do n=$((n + 1)); done
echo "n=$n"

# 3) when streaming is not needed, just use for
n=0
for line in a b c; do n=$((n + 1)); done
echo "n=$n"

The manual also states the precondition for lastpipe: "If the lastpipe option is enabled ... and job control is not active, the last element of a pipeline may be run by the shell process." On this machine shopt -p lastpipe prints shopt -u lastpipe; job control is on in interactive shells, so this option is only dependable inside scripts.

10. Failure nine: an unquoted here-doc delimiter expands

This is the one I have hit the most this year, and the only one that rewrites what you are writing.

The manual, section 3.6.6: "If any part of word is quoted, the delimiter is the result of quote removal on word, and the lines in the here-document are not expanded. If word is unquoted, delimiter is word itself, and the here-document text is treated similarly to a double-quoted string."

Measured, writing the same two lines with each form:

FormWhat landed on disk
Unquotedunquoted: /c/Users/xuany and X
Single-quotedquoted: $HOME and $(printf X)

So when the here-doc is used to write a script or a config file, every $variable, $(command) and backtick is executed at the moment of writing. What lands on disk is the output, not the source. Worse, the output is usually valid text that passes syntax checks, and the problem only surfaces on another machine where the variable resolves differently.

There is a second, quieter trap: an unterminated here-doc produces one warning, still exits 0, and feeds everything after it to the command as here-doc content. I built a script with a missing EOF to measure it:

w2.sh: line 2: warning: here-document at line 1 delimited by end-of-file (wanted `EOF')
body
w2 exit code=0

body is the swallowed line, still printed; bash -n w2.sh also returns 0. Treat that warning as an error, or you get a script that "finished" with a large piece of its content missing.

Troubleshooting: five real errors and their fixes

All five strings below are exactly what this machine printed, with the exit codes.

Error one: an odd number of quotes

w1.sh: line 1: unexpected EOF while looking for matching `"'

Exit code 2. One quote was never closed, so the parser read to the end of file. Fix: run bash -n script.sh first (this class returns 2 and gets caught), then check quote nesting, especially on lines that embed SQL, regexes or JSON inside single quotes.

Error two: an unterminated here-doc

w2.sh: line 2: warning: here-document at line 1 delimited by end-of-file (wanted `EOF')

Exit code 0 — it is only a warning. Fix: quote the delimiter as 'EOF' and align the indentation; with the tab-stripping form remember that only tabs are stripped, so space-indented delimiters still do not match.

Error three: an if without fi

w3.sh: line 3: syntax error: unexpected end of file from `if' command on line 1

Exit code 2. bash 5.3 words this more helpfully than older versions: it names the line that opened the block. Fix: bash -n plus editor bracket matching; do not rely on indentation.

Error four: [ receives an empty variable

bash: line 1: [: =: unary operator expected

Exit code 2. In [ $e = x ] the empty $e disappears, so [ sees only two arguments. Two fixes, pick one and do not mix them:

[ "$e" = x ]        # quote it so it becomes an empty string
[[ $e = x ]]        # bash [[ ]] does not word-split; empty is safe

Error five: set -u meets an unset variable

bash: line 1: nope: unbound variable

Exit code 1. Positional parameters behave the same: set -u; echo "${1}" with no arguments gives bash: line 1: 1: unbound variable (write it as a dollar sign followed by a digit and the message prints that dollar sign too). Fix: give optional values a default with ${nope:-} and make required ones fail loudly with ${nope:?nope is required}. Worth knowing: set -u is safe for $@, $* and empty arrays — iterating an empty array and calling f "$@" both measured clean.

11. A header you can copy

Nine failures, five lines:

#!/usr/bin/env bash
set -euo pipefail
shopt -s inherit_errexit
trap 'echo "FAILED at line $LINENO: $BASH_COMMAND" >&2' ERR
IFS=$'\n\t'

Measured effect: rewriting the opening script with this header (and making cd and note explicit) stops immediately, exits 1, and prints no such dir: /opt/app/release.

Line by line: -e exits on failure, -u rejects unset variables, pipefail makes the left side of a pipe visible. inherit_errexit extends -e into command substitutions. trap ... ERR reports the failing line, but only reaches functions and command substitutions when set -E is on — the manual's -E entry says: "If set, any trap on ERR is inherited by shell functions, command substitutions, and commands executed in a subshell environment. The ERR trap is normally not inherited in such cases." IFS narrows word splitting.

This header is not safety. Several of the nine still slip under it, as measured:

The reliable move is to make critical steps explicit, so that the check itself becomes the failure point:

if ! out=$(cp src.txt "$DIR/" 2>&1); then
  echo "copy failed: $out" >&2
  exit 1
fi

Measured, if ! out=$(false 2>&1); then reliably takes the then branch, and out=$(false) || { ... } catches it too (exit code 1). Neither depends on the exemption table, and nobody reading the code has to memorise it.

12. Four checks to run before shipping

Run these in order after writing a script; they cost less than reading logs afterwards.

Also treat bash -n as the first gate, while knowing its limits: an unclosed quote returns 2, an unclosed if returns 2, and an unterminated here-doc returns 0. That last one is the class it will wave through.

13. Boundaries: what I did not measure

So the numbers above can be checked, here is the scope:

FAQ

Q: Is set -euo pipefail enough?

No. It covers "a failing command should stop the script". A while loop in a pipeline subshell, an empty variable building a path, and an unterminated here-doc all get past it. What actually holds is an explicit if ! cmd; then around the steps that matter.

Q: Why does local out=$(cmd) not trigger set -e?

Because the status belongs to local. The manual lists three ways local returns non-zero: used outside a function, an invalid name, or a readonly variable. Whether the assigned command failed is not among them. Splitting it into local out and out=$(cmd) makes the second line carry the real status.

Q: Which loop should I use to read a file?

If the variable must survive the loop, use while read -r line; do ...; done < file or process substitution. Consider lastpipe only inside scripts with job control off. If streaming is unnecessary, a plain for is simplest. A while on the right of a pipe is the one shape that silently loses the counter.

Q: Is set -e still worth using?

Yes, with explicit checks. BashFAQ/105 concludes that "its rules are extremely convoluted" and records several positions, from "do not use it, write your own error handling" to "use it but know every trap". Mine: small utility scripts get set -euo pipefail plus trap ERR; anything that produces artifacts or publishes gets explicit checks on the critical steps.

Closing

None of these nine is a bash bug. They share one root: an exit code answers a very narrow question — did the last command succeed. When a script reports success, ask three more things: did the artifact actually change, was the error swallowed by || true or local, and is the $? you are testing already overwritten. Writing those three questions as assertions in the script beats adding another option to set -e.

👉 Join Xiaomi MiMo Platform: Leading AI model platform with cost-effective inference

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

As an Amazon Associate, I earn from qualifying purchases at no extra cost to you.

☁️ DigitalOcean Cloud ⚡ Vultr VPS 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🧠 AI & LLM Books 🏗️ System Design Books 🐳 Docker & K8s Books 🐧 Linux Admin Books 🐍 Python Books 🗄️ Database Books 🚀 DevOps & SRE Books 🤖 Xiaomi MiMo Platform
← Back to Home