Error Handling

The Silent Failure That Cost Hours

My deployment script ran successfully - or so I thought. Green text, "Deployment complete!" message, exit code 0. Perfect.

Except nothing was deployed. The script had failed silently halfway through, continued running, and reported success. Three hours later, users reported the application wasn't updated. I spent two hours debugging before I realized the issue: no error handling.

One try/catch block would have saved three hours of downtime and significant embarrassment.

Understanding PowerShell Errors

PowerShell has two types of errors:

Terminating Errors

Stop script execution immediately:

• Syntax errors

• Cmdlet failures with -ErrorAction Stop

• Throw statements

• Critical failures

Non-Terminating Errors

Script continues despite error:

• File not found (by default)

• Permission denied (by default)

• Cmdlet failures without -ErrorAction Stop

# Non-terminating - script continues
Get-Item "C:\NonExistent\file.txt"
Write-Host "This still runs"

# Terminating - script stops
Get-Item "C:\NonExistent\file.txt" -ErrorAction Stop
Write-Host "This won't run"

Try/Catch/Finally

Basic Try/Catch

try {
    Get-Item "C:\NonExistent\file.txt" -ErrorAction Stop
    Write-Host "File exists"
}
catch {
    Write-Warning "File not found: $_"
}

Catching Specific Exceptions

try {
    $content = Get-Content "C:\file.txt" -ErrorAction Stop
}
catch [System.IO.FileNotFoundException] {
    Write-Error "File doesn't exist"
}
catch [System.UnauthorizedAccessException] {
    Write-Error "Permission denied"
}
catch {
    Write-Error "Unexpected error: $_"
}

Finally Block

Always executes, regardless of errors:

try {
    $file = [System.IO.File]::Open("C:\data.txt", "Open")
    # Process file
}
catch {
    Write-Error "Error processing file: $_"
}
finally {
    if ($file) {
        $file.Close()
        Write-Host "File closed"
    }
}

The $Error Variable

PowerShell stores errors in $Error array:

# Most recent error
$Error[0]

# Clear error history
$Error.Clear()

# Count errors
$Error.Count

# Get error details
$Error[0].Exception
$Error[0].Exception.Message
$Error[0].ScriptStackTrace
$Error[0].InvocationInfo

ErrorAction Parameter

Control error behavior per cmdlet:

# Stop on error
Get-Item "C:\missing.txt" -ErrorAction Stop

# Continue silently
Get-Item "C:\missing.txt" -ErrorAction SilentlyContinue

# Show warning instead of error
Get-Item "C:\missing.txt" -ErrorAction Inquire

# Available options:
# - Stop: Terminate
# - Continue: Show error, continue (default)
# - SilentlyContinue: Hide error, continue
# - Inquire: Prompt user
# - Ignore: Completely ignore (don't log to $Error)

$ErrorActionPreference

Set default error behavior for script:

# Default
$ErrorActionPreference = "Continue"

# Stop on any error
$ErrorActionPreference = "Stop"

# Silent mode
$ErrorActionPreference = "SilentlyContinue"

Throwing Custom Errors

function Test-Configuration {
    param([string]$ConfigPath)
    
    if (-not (Test-Path $ConfigPath)) {
        throw "Configuration file not found: $ConfigPath"
    }
    
    $config = Get-Content $ConfigPath | ConvertFrom-Json
    
    if (-not $config.Server) {
        throw "Invalid configuration: Server property missing"
    }
}

try {
    Test-Configuration -ConfigPath "C:\config.json"
}
catch {
    Write-Error "Configuration error: $_"
    exit 1
}

Real-World Error Handling

Robust Script Template

[CmdletBinding()]
param(
    [Parameter(Mandatory=$true)]
    [string]$ServerName
)

$ErrorActionPreference = "Stop"
$logPath = "C:\Logs\script-$(Get-Date -Format 'yyyy-MM-dd').log"

function Write-Log {
    param([string]$Message, [string]$Level = "INFO")
    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    $logMessage = "$timestamp [$Level] $Message"
    $logMessage | Out-File -FilePath $logPath -Append
    
    switch ($Level) {
        "ERROR" { Write-Error $Message }
        "WARNING" { Write-Warning $Message }
        default { Write-Verbose $Message }
    }
}

try {
    Write-Log "Script started for $ServerName"
    
    # Validate prerequisites
    if (-not (Test-Connection -ComputerName $ServerName -Count 1 -Quiet)) {
        throw "Server $ServerName is not reachable"
    }
    
    # Main logic with nested error handling
    try {
        $result = Invoke-Command -ComputerName $ServerName -ScriptBlock {
            Get-Service | Where-Object {$_.Status -eq 'Running'}
        }
        Write-Log "Retrieved $($result.Count) running services"
    }
    catch {
        Write-Log "Failed to retrieve services: $_" -Level "ERROR"
        throw
    }
    
    Write-Log "Script completed successfully"
}
catch {
    Write-Log "Script failed: $_" -Level "ERROR"
    Write-Log $_.ScriptStackTrace -Level "ERROR"
    exit 1
}
finally {
    Write-Log "Script execution ended"
}

API Call with Retry

function Invoke-ApiWithRetry {
    param(
        [string]$Uri,
        [int]$MaxRetries = 3,
        [int]$DelaySeconds = 5
    )
    
    $attempt = 0
    $lastError = $null
    
    while ($attempt -lt $MaxRetries) {
        try {
            $attempt++
            Write-Verbose "Attempt $attempt of $MaxRetries"
            
            $response = Invoke-RestMethod -Uri $Uri -ErrorAction Stop
            return $response
        }
        catch {
            $lastError = $_
            Write-Warning "Attempt $attempt failed: $($_.Exception.Message)"
            
            if ($attempt -lt $MaxRetries) {
                Write-Verbose "Waiting $DelaySeconds seconds before retry..."
                Start-Sleep -Seconds $DelaySeconds
            }
        }
    }
    
    throw "All $MaxRetries attempts failed. Last error: $lastError"
}

Common Pitfalls

1. Not Using -ErrorAction Stop

Problem: try/catch doesn't catch non-terminating errors Solution: Use -ErrorAction Stop in try blocks

2. Catching All Errors Generically

Problem: Can't respond appropriately to different failures Solution: Catch specific exception types when possible

3. Swallowing Errors

Problem: Empty catch blocks hide problems Solution: Always log errors, even if handling them

# Bad - silent failure
try {
    Do-Something
}
catch {
    # Nothing - error lost
}

# Good - logged
try {
    Do-Something
}
catch {
    Write-Log "Operation failed: $_" -Level "ERROR"
    throw  # Re-throw if can't recover
}

Key Takeaways

• Two error types: Terminating and non-terminating

• Try/Catch/Finally: Standard error handling pattern

• -ErrorAction Stop: Makes errors catchable

• $Error variable: Stores error history

• Throw: Create custom errors

• Always log errors: Even if handling them

• Use finally: For cleanup that must happen

What You've Learned

✅ Understanding error types in PowerShell ✅ Try/Catch/Finally blocks ✅ Using $Error variable and ErrorAction ✅ Throwing custom errors ✅ Building robust error handling ✅ Retry logic patterns ✅ Logging errors effectively

Next Steps

Now that your scripts handle errors gracefully, let's make them reusable. In Functions and Modules, you'll learn:

• Creating functions

• Advanced function features

• Building modules

• PowerShell Gallery

• Code reusability patterns

Transform your scripts into shareable tools.

---

Ready to build reusable code? Continue to Functions and Modules →