A Bash pipeline can return success even when an earlier stage failed. Without pipefail, its status normally comes from the final command. A formatter or logger at the end can therefore hide a producer failure. To investigate, capture the individual stage results with PIPESTATUS immediately after the pipeline, before running a diagnostic command.
This tutorial uses Bash specifically, not an unspecified sh interpreter. The examples deliberately generate exit statuses without touching server files or changing services. They help distinguish an aggregate return code from evidence about each stage.
Reproduce the hidden failure safely
Run this block in Bash. Parentheses isolate the shell-option changes from your existing terminal session. The producer prints one line and exits with status 7; cat successfully consumes that line.
(
set +e
set +o pipefail
bash -c 'printf "sample\n"; exit 7' | cat
result=$?
printf 'Pipeline status without pipefail: %s\n' "$result"
)Expect the sample line followed by an aggregate status of 0. That zero does not establish that the producer completed its job. It means the final stage succeeded under this option setting. The assignment captures the status immediately; running a successful printf first would overwrite the evidence available through the next $? expansion.
Enable pipefail when earlier failures must affect the result
The GNU Bash reference manual source, available here through a source mirror, defines pipefail as returning the rightmost nonzero stage status, or zero if every stage succeeds. It is not a count of failures, nor a guarantee that every program completed its intended business task.
(
set +e
set -o pipefail
bash -c 'printf "sample\n"; exit 7' | cat
result=$?
printf 'Pipeline status with pipefail: %s\n' "$result"
)Here the aggregate status is 7. If several stages fail, the rightmost failing stage determines the aggregate; it need not be the stage that failed first in time. Read the individual statuses when diagnosis requires more detail.
The examples disable errexit inside their subshells so the deliberate failures can be inspected. They do not prescribe changing production error-handling settings. With errexit enabled, whether execution continues also depends on the command’s surrounding shell context; pipefail and errexit are separate mechanisms.
Copy PIPESTATUS before printing anything
Bash maintains PIPESTATUS as an array describing the most recently executed foreground pipeline. A simple command can replace that information too. Capture the array in the very next command, rather than printing a heading and trying to inspect it afterwards.
(
set +e
set -o pipefail
bash -c 'exit 7' | bash -c 'exit 4' | cat
stages=("${PIPESTATUS[@]}")
printf 'Stage statuses: %s %s %s\n' "${stages[0]}" "${stages[1]}" "${stages[2]}"
)The expected stage statuses are 7, 4 and 0 in pipeline order. With pipefail the aggregate would be 4, because the middle command is the rightmost failure. This example saves the array, not the aggregate. An intervening result=$? assignment would itself replace the live PIPESTATUS array, so do not use that sequence when you need the original stage details.
Interpret nonzero results in context
A nonzero stage does not always mean a broken system. Search tools may distinguish no matches from operational errors. A downstream command that intentionally stops early can also cause an upstream writer to encounter a closed pipe. Read each program’s documented status meanings before turning every nonzero result into an incident.
Conversely, pipefail does not validate output completeness, detect semantically wrong records, roll back partial writes, or stop commands from starting. For a real export, check the producer’s contract, the saved stage statuses and the resulting artifact before reporting success. Avoid piping sensitive diagnostics to external destinations merely to make logging convenient.
Checklist for a reliable incident note
- Record that the interpreter was Bash and note the pipefail setting used.
- Capture the relevant status immediately, before another command runs.
- Use PIPESTATUS when the identity of the failing stage matters.
- Separate expected no-result outcomes from genuine execution errors.
- Validate the actual output rather than treating a return code as a complete health check.
When the pipeline is collecting service evidence, preserve the original failure context before attempting recovery. Our failed-service evidence capture tutorial covers why restarting first can erase useful context.
Does pipefail stop the whole pipeline immediately? No; it changes the aggregate status rule. Does printing PIPESTATUS later recover old results? No. Save the array immediately and print the saved copy.
Educational disclaimer: This tutorial is for educational purposes. Test carefully before using steps in production. WhileNetworking is not responsible for misuse, damage, data loss or production issues.
