Error Handling and Debugging

# CHAPTER 16

Error Handling and Debugging #

1. Introduction #

2. Learning Objectives #

• Trace script execution line-by-line using the -x debugging flag.

• Enforce strict, fail-fast execution logic using set -e and set -u.

• Understand and utilize explicit exit codes (exit 1) to signal failure.

• Route error messages specifically to the standard error stream (>&2).

• Implement defensive scripting checks to validate environment assumptions.

3. The X-Ray Debugger (sh -x) #

# Execute the script in trace/debug mode
sh -x deploy_app.sh

The terminal will print every single line of code with a + sign *before* it actually executes it, and it will dynamically reveal the exact data currently residing inside the variables. It is the ultimate forensic tool for identifying logic bugs and variable expansion failures.

4. Strict Mode (set -e) #

#!/bin/sh
# Enable Strict Execution Rules
set -e
set -u

• set -e (Exit on Error): If ANY command in the script fails (returns a non-zero exit code), the entire script instantly aborts. This prevents the catastrophic "cd fails, rm destroys everything" scenario.

• set -u (Unbound Variables): If you attempt to use a variable that you never defined, the script instantly aborts. This prevents devastating typos (e.g., executing rm -rf /$TARTGET instead of TARGET).

5. Explicit Exit Codes #

#!/bin/sh
TARGET="/var/log/syslog"

if [ ! -f "$TARGET" ]; then
    # Route the text directly to Channel 2 (stderr)
    echo "CRITICAL: Log file missing!" >&2  
    
    # Abort script and return a Failure code to the operating system
    exit 1  
fi

echo "Processing data..."
exit 0  # Script finished perfectly.

6. Defensive Scripting #

Bad Practice (Assuming Success):

# What if the folder doesn't exist? The copy fails.
cp file.txt /backup/folder/

Defensive Practice (Verifying Success):

# Use the Logical OR (||) to define a fallback action
cp file.txt /backup/folder/ || { echo "Copy failed!" >&2; exit 1; }

*(The { } syntax allows you to group multiple commands together as the fallback action!).*

7. Diagrams/Visual Suggestions #

8. Best Practices #

• Custom Error Functions: Instead of typing echo "Error" >&2 && exit 1 fifty times throughout a massive script, professional engineers write a dedicated error function at the top of the file:

  die() {
      echo "[FATAL ERROR] $1" >&2
      exit 1
  }
  # Usage later in the script:
  [ -f "config" ] || die "Configuration file missing!"
  ```

### 9. Common Mistakes
- **Using `set -e` blindly:** `set -e` is powerful but volatile. If your script uses `ping -c 1 8.8.8.8` just to casually check if the internet is up, and the ping fails, `set -e` will instantly annihilate the entire script! If you *expect* a command to occasionally fail and you want to handle it manually, you must explicitly bypass `set -e` by appending `|| true` to the end of the command (e.g., `ping -c 1 8.8.8.8 || true`).

### 10. Mini Project: The Bulletproof Script
Let's build a script featuring Strict Mode, Defensive Scripting, and a Custom Error Function.
1. `nano secure_backup.sh`
2. Write the code:

sh #!/bin/sh set -e set -u

# Define a professional error handler die() { echo "ERROR: $1" >&2 exit 1 }

echo "Starting secure backup protocol..."

# Defensive Check 1: Are we root? [ "$(id -u)" -eq 0 ] || die "Script must be run as root."

# Let's intentionally trigger the set -u failure! # We will misspell the variable TARGET as TARGGET TARGET="/tmp/importantdata" echo "Attempting to copy $TARGGET..." cp file.txt "$TARGGET"

• Q: A junior developer writes a backup script that begins with the command cd /mnt/backupdrive. The next line is rm -rf old_backups/*. They execute the script on a server where the backup drive unexpectedly failed to mount. Explain the catastrophic sequence of events that occurs next, and state the exact directive required at the top of the script to prevent it.

• Q: Explain the structural behavior of the || (Logical OR) operator when utilized in Defensive Scripting. Walk me through the execution flow of the command: mkdir /tmp/data || exit 1.

• Q: You review a colleague's code and notice they appended || true to the end of a curl command. Given that the script utilizes set -e at the top of the file, explain exactly why the engineer added the || true override.

16. Next Chapter Recommendation #