Identifying Failures in Bash Pipelines

Bash pipelines are an essential feature for chaining commands, but managing errors effectively within a pipeline can be challenging. By default, Bash pipelines only return the exit code of the last command, potentially obscuring failures in earlier commands. This article demonstrates how to identify failures in pipelines.

The Problem with Default Pipeline Behavior

Consider a simple pipeline

true | false | true 
echo $?

What Happens?

• The true command succeeds with exit code 0.
• The false command fails with exit code 1.
• The final true command succeeds with exit code 0.

However, the pipeline exit code ($?) reflects only the last command in the chain, which is true. Therefore, $? will be 0, even though the pipeline includes a failure.

Using set -o pipefail

The set -o pipefail option alters the behavior of pipelines:

• The pipeline’s exit code becomes the exit code of the first failing command.

Example: Detecting Failure with pipefail

set -o pipefail 
true | false | true 
echo $?

What Happens Now?

• The false command fails with exit code 1.
• The pipeline exits with 1, even though the last command (true) succeeded.

Output:

1

This ensures that any failure within the pipeline is captured.

Using $PIPESTATUS for Detailed Exit Codes

While set -o pipefail provides the overall exit code of a pipeline, the $PIPESTATUS array allows you to inspect the exit codes of each command individually.

Example: Analyzing Each Command

true | false | true 
echo "${PIPESTATUS[@]}"

Output:

0 1 0

• ${PIPESTATUS[0]}: Exit code of true (0).
• ${PIPESTATUS[1]}: Exit code of false (1).
• ${PIPESTATUS[2]}: Exit code of the last true (0).

This makes it easy to pinpoint exactly which command failed.

Caveat: $PIPESTATUS Changes After Every Command

The $PIPESTATUS array is overwritten after every command or pipeline execution. This means that if you run another command or even check the value of $PIPESTATUS too late, its contents will reflect the exit codes of the most recent pipeline or command, not the one you intended to inspect.

Example of the Issue

true | false | true 
echo "${PIPESTATUS[@]}"  # Correct: Outputs 0 1 0 
 
# Run another command 
true 
echo "${PIPESTATUS[@]}"  # Overwritten: takes the status of the true command

In this example, the exit codes of the true | false | true pipeline are lost once true is executed, and $PIPESTATUS now only reflects the exit code of true.

Solution: Copy $PIPESTATUS to a Variable

To avoid losing the exit codes, you should copy the contents of $PIPESTATUS to another variable immediately after executing the pipeline. This way, you can safely reference the exit codes later in your script.

How to Copy $PIPESTATUS

Use an array variable to store the values:

Create the following script and save it as test_fail.sh

#!/bin/bash 
true | false | true 
pipe_status=("${PIPESTATUS[@]}")  # Copy PIPESTATUS immediately 
 
# Access the copied values later 
echo "Saved PIPESTATUS: ${pipe_status[@]}" 
 
# Example: Check each command's exit code 
if [ "${pipe_status[0]}" -ne 0 ]; then 
  echo "Command 1 failed" 
fi 
if [ "${pipe_status[1]}" -ne 0 ]; then 
  echo "Command 2 failed" 
fi 
if [ "${pipe_status[2]}" -ne 0 ]; then 
  echo "Command 3 failed" 
fi

Make it executable and run it

chmod +x ./test_fail.sh 
./test_fail.sh 
Saved PIPESTATUS: 0 1 0 
Command 2 failed

Conclusion

Understanding and leveraging $PIPESTATUS and set -o pipefail is crucial for writing robust Bash scripts that handle errors effectively in pipelines. However, it’s important to be aware of the caveat that $PIPESTATUS is overwritten after every command or pipeline execution. This can lead to unintentional loss of exit codes if not handled carefully.

To address this, always copy the contents of $PIPESTATUS into a separate variable immediately after the pipeline executes. By doing so, you preserve the exit codes for detailed inspection and avoid potential overwrites.

Incorporating these best practices ensures:

• Reliable error detection within pipelines.
• Accurate handling of failures for each command in the pipeline.
• Robust scripts that are easier to debug and maintain.

By mastering these techniques, you can write more reliable and professional Bash scripts that gracefully handle complex scenarios.