> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bash 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
```bash theme={"dark"}
# 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.
```bash theme={"dark"}
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:
```bash theme={"dark"}
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.
```bash theme={"dark"}
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
```
Tired of Poor Bash Skills? Fix That With Deep Grasping!
Learn More
