Error Handling and Debugging

Control how PowerShell handles failures: understand terminating vs non-terminating errors, use try/catch/finally for structured error handling, inspect the $Error variable, and debug scripts with Set-PSDebug and Write-Verbose.

🧒 Simple Explanation (ELI5)

Errors in PowerShell are like speed bumps on a road. Some are small bumps the car can roll over (non-terminating errors—the script keeps going). Others are big crashes that stop the car entirely (terminating errors). A try/catch block is like a safety net under a trapeze artist: if the artist falls (an error happens), the net catches them and your cleanup code in finally runs regardless. Without error handling, one bad server in a loop of 50 stops the whole script.

🔧 Why Do We Need It?

• Silent failures: by default, many PowerShell errors are non-terminating—the script continues and you never know it skipped 20 servers.
• Cleanup: the finally block runs whether or not an error occurred, ensuring connections are closed and locks are released.
• Pipeline exit codes: CI/CD needs a non-zero exit code on failure; unhandled errors may still exit 0, marking a broken build as "passed."
• Context in failures: catching errors lets you add context—server name, function name, input value—to the error message before logging it.

⚙️ Technical Explanation

PowerShell has two error types: terminating errors stop execution immediately (thrown exceptions, parameter validation failures, methods that throw .NET exceptions). Non-terminating errors write to the error stream and continue execution by default.

$ErrorActionPreference (global) and -ErrorAction (per-cmdlet) control behavior: Continue (default, show error and continue), Stop (convert non-terminating to terminating), SilentlyContinue (suppress and continue), Ignore (suppress completely).

The $Error automatic variable is an array of all errors in the session. $Error[0] is the most recent. Each error has .Exception.Message, .InvocationInfo.Line, .ScriptStackTrace, and more.

📊 Visual Representation

⌨️ Commands / Syntax

# Make all errors terminating in production scripts
$ErrorActionPreference = 'Stop'

# Basic try/catch/finally
try {
    $result = Invoke-RestMethod -Uri "https://api.example.com/health"
    Write-Host "API status: $($result.status)"
}
catch [System.Net.WebException] {
    Write-Error "Network error reaching API: $($_.Exception.Message)"
}
catch {
    Write-Error "Unexpected error: $($_.Exception.Message)"
    Write-Error "Stack trace: $($_.ScriptStackTrace)"
}
finally {
    Write-Verbose "Health check attempt completed"
}

# Catch specific .NET exception types
try {
    [System.IO.File]::ReadAllText("C:\missing.txt")
}
catch [System.IO.FileNotFoundException] {
    Write-Warning "Config file not found. Using defaults."
}

# throw to create custom errors
function Validate-Environment {
    param([string]$Env)
    if ($Env -notin @('dev','staging','prod')) {
        throw [System.ArgumentException]"Invalid environment: $Env"
    }
}

# Check $Error for recent failures
try { Get-Item C:\nonexistent -ErrorAction Stop }
catch {}
$Error[0].Exception.Message
$Error[0].InvocationInfo.PositionMessage

# Debugging with Write-Verbose (only shows with -Verbose)
$VerbosePreference = 'Continue'  # or pass -Verbose to function
Write-Verbose "Processing server: $serverName"

# Set-PSDebug for step-through debugging (dev only)
Set-PSDebug -Trace 1   # trace each line
# ... run code ...
Set-PSDebug -Off        # disable tracing

# Check exit code from external commands
& git status
if ($LASTEXITCODE -ne 0) {
    throw "git status failed with exit code $LASTEXITCODE"
}

💼 Example (Real-world Use Case)

A deployment script iterates over 20 Azure web apps, calling the management API to trigger slot swaps. Without error handling, one API timeout stops the entire script and the remaining 19 apps are not deployed. With try/catch around each iteration, failures are logged with the app name, added to a $failures array, and the loop continues. At the end, if $failures.Count -gt 0, the script exits with a non-zero code and the CI/CD pipeline fails, triggering an alert with a complete list of failed apps.

🧪 Hands-on

1. Set $ErrorActionPreference = 'Stop' and try running Get-Item C:\nonexistent. It should now throw instead of printing a red error and continuing.
2. Wrap the same command in try/catch and handle the FileNotFoundException specifically.
3. Read $Error[0].Exception.Message and $Error[0].InvocationInfo.PositionMessage after a caught error to inspect its contents.
4. Add Write-Verbose lines to a function and test with -Verbose on and off.
5. Call an external command (like git status in a non-repo folder) and check $LASTEXITCODE.

🐛 Debugging Scenario

Problem: a script runs successfully but the CI/CD pipeline shows it as passed even though several operations actually failed.

• Cause: the script uses ErrorAction SilentlyContinue in several places, suppressing errors and never setting $LASTEXITCODE or throwing.
• Diagnose: remove SilentlyContinue and add -Verbose to see which operations are being silently swallowed. Check if $Error contains errors after a run that appeared successful.
• Fix: change to $ErrorActionPreference = 'Stop' globally, use try/catch to handle expected failures explicitly, and add exit 1 (or throw) at the end when any failure was accumulated. The pipeline will then correctly fail the build.

🎯 Interview Questions

🌐 Real-world Usage

Azure automation runbooks use try/catch to handle API timeouts and rate limits, retrying with exponential backoff. CI/CD deployment scripts use $ErrorActionPreference = 'Stop' and structured error accumulation to ensure pipelines fail when deployments fail, not just when unhandled exceptions occur. Operations monitoring scripts catch and log per-server failures without stopping the whole health-check run.

📝 Summary

Non-terminating errors are the silent killers of automation scripts. Use $ErrorActionPreference = 'Stop' to convert them to terminating errors and let try/catch handle them. Catch specific exception types for precise handling. Always add context to error messages before logging. Use finally for cleanup. Check $LASTEXITCODE after external command calls. Write-Verbose is your primary debugging tool in production-safe scripts.