PowerShell Error Handling Best Practices

PowerShell Error Handling Best Practices

Bad error handling makes scripts fragile. Good error handling makes them professional. Here’s how to write PowerShell that fails gracefully.

The Basics

-ErrorAction Parameter

# Different levels
Stop      # Throw exception (use with Try/Catch)
Continue  # Write to $error and continue (default)
SilentlyContinue # Suppress error message
Inquire   # Ask user what to do

# Examples
Get-Item C:\Missing -ErrorAction Stop
Get-Item C:\Missing -ErrorAction SilentlyContinue

Try/Catch/Finally

try {
    # Risky operation
    Get-Content "C:\important.txt" -ErrorAction Stop
    
    # Success path
    Write-Host "File found!"
}
catch {
    # What to do on failure
    Write-Host "Error: $($_.Exception.Message)"
    
    # Log the error
    $Error | Out-File "C:\Logs\errors.log" -Append
}
finally {
    # Always runs - cleanup
    Remove-Item $tempFile -ErrorAction SilentlyContinue
}

Types of Errors

Terminating vs Non-Terminating

# Terminating - stops execution
# Use -ErrorAction Stop to convert

# Non-terminating - continues
Get-ChildItem C:\ -Recurse -ErrorAction SilentlyContinue

# Make terminating
$ErrorActionPreference = "Stop"

Catch Specific Errors

try {
    Get-ADUser "doesntexist"
}
catch [Microsoft.ActiveDirectory.Management.ADIdentityNotFoundException] {
    Write-Host "User not found"
}
catch [System.UnauthorizedAccessException] {
    Write-Host "Access denied"
}
catch {
    Write-Host "Unexpected error: $_"
}

Logging Errors

function Write-ErrorLog {
    param([string]$Message)
    
    $LogPath = "$env:TEMP\ScriptErrors.log"
    $Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    
    "$Timestamp - $Message" | Out-File $LogPath -Append
}

# Usage
try {
    Invoke-RestMethod "https://api.example.com/data" -ErrorAction Stop
}
catch {
    Write-ErrorLog "API call failed: $($_.Exception.Message)"
    throw
}

Validation Patterns

# Pre-flight checks
function Install-App {
    param([string]$InstallerPath)
    
    # Validate input
    if (-not (Test-Path $InstallerPath)) {
        throw "Installer not found: $InstallerPath"
    }
    
    # Validate disk space
    $FreeSpace = (Get-PSDrive C).Free
    if ($FreeSpace -lt 1GB) {
        throw "Insufficient disk space"
    }
    
    # Proceed with install
}

Retry Logic

function Invoke-WithRetry {
    param(
        [scriptblock]$ScriptBlock,
        [int]$MaxAttempts = 3,
        [int]$DelaySeconds = 5
    )
    
    for ($i = 1; $i -le $MaxAttempts; $i++) {
        try {
            & $ScriptBlock -ErrorAction Stop
            return
        }
        catch {
            if ($i -eq $MaxAttempts) {
                throw "Failed after $MaxAttempts attempts: $_"
            }
            Write-Host "Attempt $i failed, retrying..."
            Start-Sleep -Seconds $DelaySeconds
        }
    }
}

# Usage
Invoke-WithRetry -ScriptBlock {
    Test-NetConnection -ComputerName "api.example.com" -Port 443
} -MaxAttempts 3 -DelaySeconds 5

$PSItem vs $_

# Both work the same
catch {
    $_.Exception.Message      # The error message
    $_.Exception.GetType()    # Exception type
    $_.ScriptStackTrace      # Where it happened
    $_.TargetObject           # What failed
}

Common Mistakes

❌ Bad:

Get-Item C:\file.txt
if ($?) { Write-Host "Success" }

✅ Good:

try {
    Get-Item C:\file.txt -ErrorAction Stop
    Write-Host "Success"
}
catch {
    Write-Host "Failed"
}

Wrap-Up

Always assume things can fail. Use Try/Catch, log errors, and validate inputs. Your future self will thank you.

Questions? Drop them below!