ERR Trap

The ERR trap in Bash is an event-driven exception handling mechanism that executes a specified command or function whenever a command, pipeline, list, or arithmetic evaluation terminates with a non-zero exit status. It intercepts failures synchronously at the point of execution, temporarily suspending the script’s normal flow to evaluate the trap payload.

Syntax

# Execute a string/command on error
trap 'command_to_execute' ERR


# Execute a predefined function on error
trap function_name ERR


# Remove the ERR trap
trap - ERR

Execution Mechanics

When a command yields a non-zero exit status, Bash evaluates the ERR trap payload in the current shell environment. Once the trap completes, script execution resumes at the command immediately following the one that failed, unless the trap explicitly invokes exit or the shell is operating under set -e (errexit). If set -e is enabled, the ERR trap executes immediately before the shell terminates.

Contextual Variables

During the execution of an ERR trap, Bash populates specific environment variables that provide context about the failure:

• $?: Contains the integer exit status (1-255) of the command that triggered the trap.
• $BASH_COMMAND: Contains the literal string of the command that failed, exactly as it was evaluated by the shell.
• $LINENO: Contains the script line number where the failing command was executed.

trap 'echo "Command $BASH_COMMAND failed at line $LINENO with status $?"' ERR

Scope and Inheritance (errtrace)

By default, ERR traps are strictly bound to the execution environment in which they are declared. They are not inherited by shell functions, command substitutions, or subshells.

To force the ERR trap to propagate down the call stack into sub-environments, you must enable the errtrace option:

set -E

# or
set -o errtrace

Trigger Exceptions

The ERR trap adheres to the exact same suppression rules as the set -e (errexit) option. The trap will not trigger if the failing command is part of a conditional test or a boolean chain where the failure is considered handled by the shell’s logic.

Specifically, the ERR trap is suppressed when the failing command is:

1. Part of the condition in an if or elif statement.
2. Part of the condition in a while or until loop.
3. Part of a boolean list connected by && or ||, except for the final command in the chain.
4. Negated using the ! operator (e.g., ! false).
5. Any command in a pipeline other than the last command, unless set -o pipefail is enabled.

trap 'echo "Error"' ERR


# WILL trigger the trap
ls /nonexistent_directory


# WILL NOT trigger the trap (suppressed by boolean OR)
ls /nonexistent_directory || true


# WILL NOT trigger the trap (suppressed by conditional context)
if ls /nonexistent_directory; then
    echo "Success"
fi

Master Bash with Deep Grasping Methodology!

Learn More