A bash script runs `build_tool | tee build.log`, then stores `rc=$?` on the next line, then checks `${PIPESTATUS[0]}` — and always sees 0 even when build_tool fails. Why, and how do you capture each stage's status correctly?

## What PIPESTATUS is `PIPESTATUS` is a bash array variable containing the exit statuses of the processes in the **most recently executed foreground pipeline** — including a pipeline of exactly one command. It is the only way to see per-stage statuses, because `$?` can hold just one number. ```bash false | true | cat echo "${PIPESTATUS[@]}" # 1 0 0 ``` Index 0 is the leftmost stage. It is maintained whether or not `pipefail` is enabled; the two mechanisms are independent, and after `set -o pipefail; false | true` you get `$?` of 1 while the array still reads `1 0`. ## Why the naive read is always 0 The words "most recently executed" are load-bearing. Every command the shell runs afterwards replaces the array — and in bash a bare variable assignment *is* a command: ```bash false | true rc=$? # this assignment succeeds... echo "${PIPESTATUS[*]}" # 0 <- ...and PIPESTATUS is now just (0) ``` So the script in the question has already destroyed the data before it reads it. The same happens with an `echo`, a `[[ ... ]]` test, a `date` call for a log line, or anything else slipped between the pipeline and the read. This is the single most common `PIPESTATUS` bug, and it is silent: the array still exists and still contains a plausible-looking 0. ## The correct pattern Copy the entire array on the line immediately following the pipeline, before any other command: ```bash build_tool | tee build.log statuses=("${PIPESTATUS[@]}") # first thing after the pipeline build_rc=${statuses[0]} tee_rc=${statuses[1]} if (( build_rc != 0 )); then echo "build_tool failed with ${build_rc}" >&2 exit "${build_rc}" fi ``` Three details make that copy correct: - `"${PIPESTATUS[@]}"` with `@` and quotes expands to one word per element, which is what the array assignment `( ... )` needs. `"${PIPESTATUS[*]}"` would collapse the statuses into one space-joined string — fine for printing, wrong for copying. - `$PIPESTATUS` with no subscript is *not* the array. Unsubscripted array expansion in bash yields element 0, so it silently gives you only the first stage's status. - If you also want `$?`, capture it in the *same* statement or derive it from the copy; a separate `rc=$?` line placed first is exactly the bug. Inside a function, declare the copy local so it does not leak: `local -a statuses=("${PIPESTATUS[@]}")`. ## Choosing between PIPESTATUS and pipefail They answer different questions, and mature scripts use both. `pipefail` answers "did anything fail?" with a single number — right when every stage failing is equally fatal. `PIPESTATUS` answers "which stage failed, with what?" — right when the stages need different treatment. The canonical case is tolerating a benign non-zero from one stage while still failing on the others: ```bash log_reader | grep -c WARN | tee warn_count.txt st=("${PIPESTATUS[@]}") (( st[0] == 0 )) || { echo "reader failed: ${st[0]}" >&2; exit 1; } # grep returning 1 just means "no matches" - not an error here (( st[1] <= 1 )) || { echo "grep errored: ${st[1]}" >&2; exit 1; } (( st[2] == 0 )) || { echo "tee failed: ${st[2]}" >&2; exit 1; } ``` That granularity is impossible with `pipefail` alone, which flattens all of it to one number. ## Portability and scope `PIPESTATUS` is a bash feature. `zsh` has its own differently-named equivalent, and `dash` and other strict POSIX `/bin/sh` implementations have nothing comparable — a script relying on it must run under bash via an explicit `#!/usr/bin/env bash` shebang. There is no POSIX-portable way to recover per-stage statuses, which is one honest reason to reach for a real programming language when a script's error handling gets this fine-grained. One more scope note: the array reflects the most recent **foreground** pipeline in the current shell. A pipeline you run inside a command substitution or a background job updates that inner shell's copy, not the caller's, so plan to read it in the same shell that ran the pipeline. ## Reviewing for it When you see `PIPESTATUS` referenced anywhere except the line directly after a pipeline, treat it as a defect until proven otherwise. Scan upward: if any command — assignment included — sits between the pipeline and the read, the values are gone.