PowerShell Error Handling and Logging Techniques

Every system administrator knows the sinking feeling when a script fails silently in production, leaving no trace of what went wrong or why. In the complex landscape of modern IT infrastructure, where PowerShell scripts orchestrate critical operations across thousands of systems, the difference between robust error handling and wishful thinking can mean the gap between five minutes of troubleshooting and five hours of crisis management. The ability to anticipate, capture, and respond to errors isn't just a technical skill—it's a fundamental responsibility that separates professional automation from dangerous guesswork.

Error handling in PowerShell represents the systematic approach to detecting, managing, and recovering from unexpected conditions during script execution, while logging serves as the permanent record of what happened, when it happened, and why it matters. Together, these practices form the foundation of reliable automation, providing both immediate operational resilience and long-term forensic capabilities. From simple try-catch blocks to sophisticated logging frameworks, the spectrum of available techniques offers solutions for every scenario, whether you're writing a quick administrative script or building enterprise-grade automation platforms.

This comprehensive exploration will equip you with practical knowledge spanning fundamental error types and their characteristics, strategic approaches to error interception and handling, advanced logging architectures that scale with your needs, real-world implementation patterns that you can adapt immediately, and the critical integration points between error management and operational monitoring. You'll discover not just the mechanics of these techniques, but the decision-making frameworks that help you choose the right approach for each situation, ensuring your PowerShell automation becomes more predictable, maintainable, and trustworthy.

Understanding PowerShell Error Types and Behavior

PowerShell distinguishes between two fundamental error categories that behave dramatically differently in your scripts. Terminating errors immediately halt execution of the current pipeline or script block, while non-terminating errors display a message but allow the script to continue processing subsequent commands. This distinction isn't merely academic—it fundamentally shapes how you structure error handling logic and determines which techniques will actually catch the errors you're trying to manage.

Non-terminating errors represent PowerShell's default behavior for most cmdlet failures. When you attempt to retrieve a non-existent file with Get-Content, or query a service that doesn't exist with Get-Service, PowerShell writes an error to the error stream but continues executing the next command. This design philosophy prioritizes script continuation over strict failure handling, which works well for interactive sessions but can create silent failures in automated scenarios where you need definitive success or failure outcomes.

"The most dangerous errors are the ones you never see—those non-terminating failures that let your script march forward with incomplete data, corrupted state, or false assumptions about what actually succeeded."

Terminating errors, by contrast, trigger immediate exception handling mechanisms. These include syntax errors, critical runtime failures, and any error explicitly thrown with the throw statement or generated by .NET methods that raise exceptions. When a terminating error occurs, PowerShell searches up the call stack for an appropriate error handler, and if none exists, the script terminates completely. Understanding this escalation mechanism is crucial because it determines where and how you position your error handling code.

The $ErrorActionPreference variable controls PowerShell's global response to non-terminating errors, with values ranging from 'SilentlyContinue' (suppresses error display) through 'Continue' (default behavior showing errors but continuing) to 'Stop' (converts non-terminating errors to terminating ones). This preference acts as a script-wide policy, but individual cmdlets can override it using the -ErrorAction parameter, giving you granular control over error behavior at the command level. Setting -ErrorAction Stop on critical operations transforms non-terminating errors into catchable terminating errors, bridging the gap between PowerShell's lenient defaults and your need for strict error handling.

The Error Stream and Error Records

PowerShell maintains six distinct output streams, with the error stream (stream 2) dedicated exclusively to error information. Every error generates an ErrorRecord object containing rich diagnostic information including the exception details, category information, target object, invocation details, and the complete call stack. These ErrorRecord objects accumulate in the automatic $Error variable, an array-like collection where the most recent error occupies position zero, creating a persistent audit trail of every error encountered during the session.

Each ErrorRecord exposes properties that enable sophisticated error analysis and conditional handling. The Exception property contains the underlying .NET exception with its message and inner exceptions, while CategoryInfo classifies the error by type (ResourceUnavailable, InvalidOperation, etc.) and activity. The TargetObject property references the object being processed when the error occurred, and InvocationInfo provides the exact command line, script location, and parameter values that triggered the error. Accessing these properties programmatically enables intelligent error responses that adapt to specific failure conditions rather than treating all errors identically.

Strategic Error Handling Patterns

The try-catch-finally construct represents PowerShell's primary mechanism for structured error handling, providing a clean separation between normal execution logic, error response code, and cleanup operations. The try block contains the code you want to execute with error protection, catch blocks define how to handle specific error types, and the optional finally block guarantees execution of cleanup code regardless of whether an error occurred. This pattern transforms error handling from scattered conditional checks into a coherent control flow structure that makes both success and failure paths explicit and maintainable.

try {
    $ErrorActionPreference = 'Stop'
    $content = Get-Content -Path "C:\Data\config.json"
    $config = $content | ConvertFrom-Json
    
    Connect-Service -Endpoint $config.ServiceUrl -Credential $credential
    Invoke-ServiceOperation -Operation $config.DefaultOperation
}
catch [System.IO.FileNotFoundException] {
    Write-Error "Configuration file not found. Please ensure config.json exists in C:\Data\"
    # Implement fallback configuration or graceful degradation
    $config = Get-DefaultConfiguration
}
catch [System.UnauthorizedAccessException] {
    Write-Error "Access denied reading configuration. Check file permissions and user context."
    # Log security event, alert administrators
    Send-SecurityAlert -Message "Configuration access denied for user $env:USERNAME"
}
catch {
    Write-Error "Unexpected error during initialization: $($_.Exception.Message)"
    # Log full error details for troubleshooting
    Write-ErrorLog -ErrorRecord $_ -Severity Critical
    throw  # Re-throw to prevent execution with undefined state
}
finally {
    # Cleanup operations that must occur regardless of success or failure
    if ($connection) { Disconnect-Service -Connection $connection }
    Remove-Variable -Name credential -ErrorAction SilentlyContinue
}

Multiple catch blocks enable differentiated error handling based on exception type, allowing you to respond appropriately to expected failure modes while escalating unexpected errors. The order of catch blocks matters critically—PowerShell evaluates them sequentially and executes the first match, so more specific exception types must precede general ones. The generic catch block without a type specification acts as a safety net, capturing any exception not handled by preceding blocks, ensuring no error escapes unnoticed.

"Error handling isn't about preventing failures—it's about ensuring failures happen in controlled, predictable, and recoverable ways that preserve system integrity and provide actionable diagnostic information."

Trap Statements and Legacy Error Handling

The trap statement provides an alternative error handling mechanism that predates try-catch but remains valuable in specific scenarios. Traps act as error handlers for an entire script scope or function, catching errors that occur anywhere within that scope without requiring explicit try blocks around each operation. When an error occurs, PowerShell searches up the scope hierarchy for an applicable trap, executes its code block, and then either continues or terminates based on whether the trap includes a continue or break statement.

trap [System.Net.WebException] {
    Write-Warning "Network error occurred: $($_.Exception.Message)"
    # Implement retry logic or fallback
    $script:NetworkErrorCount++
    if ($script:NetworkErrorCount -lt 3) {
        Start-Sleep -Seconds 5
        continue  # Resume execution at the statement following the error
    }
    break  # Terminate the script
}

trap {
    Write-Error "Unhandled error: $($_.Exception.GetType().FullName)"
    Write-ErrorLog -ErrorRecord $_ -Severity Critical
    break  # Terminate on unexpected errors
}

# Script code executes with trap protection
$data = Invoke-WebRequest -Uri $serviceEndpoint
Process-Data -InputData $data

While try-catch offers more explicit and localized error handling, traps excel when you need consistent error handling across large code blocks or when retrofitting error handling into existing scripts. Traps can coexist with try-catch blocks, with try-catch taking precedence within its scope, allowing you to combine both approaches strategically. However, the implicit nature of trap scoping can make code harder to follow, so modern PowerShell development generally favors explicit try-catch patterns except where trap's scope-wide coverage provides clear advantages.

Error Action Preferences and Cmdlet-Level Control

The -ErrorAction common parameter provides surgical control over individual cmdlet error behavior, overriding both the global $ErrorActionPreference and any trap or try-catch blocks in scope. Setting -ErrorAction Stop on specific cmdlets converts their non-terminating errors to terminating ones, making them catchable by try-catch blocks without affecting other commands. This granular approach enables you to apply strict error handling only where it matters, avoiding the brittleness that comes from treating every minor error as critical.

• 🎯 Stop - Converts non-terminating errors to terminating, halting execution and triggering catch blocks
• 🔄 Continue - Default behavior that displays errors but continues execution
• 🔇 SilentlyContinue - Suppresses error display but adds to $Error collection
• ⚠️ Inquire - Prompts user for action on each error (avoid in automation)
• ⏭️ Ignore - Completely suppresses errors without adding to $Error (use sparingly)

Combining -ErrorAction with -ErrorVariable creates powerful error capture patterns that don't rely on try-catch. The -ErrorVariable parameter captures errors from a specific cmdlet into a named variable, even when using -ErrorAction SilentlyContinue to suppress display. This technique enables you to check for errors without interrupting script flow, particularly useful in scenarios where errors are expected and need to be evaluated rather than handled as exceptions.

# Capture errors without stopping execution
Get-Service -Name "NonExistentService" -ErrorAction SilentlyContinue -ErrorVariable serviceError

if ($serviceError) {
    Write-Warning "Service query failed: $($serviceError[0].Exception.Message)"
    # Implement alternative logic
    $serviceExists = $false
} else {
    $serviceExists = $true
}

# Continue with logic that adapts to service availability
if ($serviceExists) {
    # Primary path
} else {
    # Fallback path
}

Comprehensive Logging Architectures

Effective logging transforms ephemeral script execution into permanent, analyzable records that support troubleshooting, compliance, performance analysis, and security forensics. A well-designed logging architecture captures not just errors but the contextual information that makes those errors meaningful—what the script was attempting, what data it was processing, what environmental conditions existed, and how the error fits into the broader operational timeline. This contextual richness distinguishes actionable logs from mere error messages, enabling rapid diagnosis and resolution of issues that might otherwise require extensive reproduction efforts.

PowerShell provides multiple logging mechanisms operating at different levels of abstraction and permanence. The Write-Verbose, Write-Warning, Write-Error, and Write-Information cmdlets write to their respective output streams, allowing consumers to filter and redirect messages based on type. The Start-Transcript cmdlet captures complete session output to file, preserving the exact sequence of commands and their results. Custom logging functions can write to structured formats like JSON or XML, send data to centralized logging systems, or integrate with Windows Event Log for enterprise visibility. Selecting and combining these mechanisms based on your specific requirements creates a logging strategy that balances detail, performance, and operational utility.

Structured Logging Implementation

Structured logging organizes log data into consistent, parseable formats that enable automated analysis, aggregation, and alerting. Rather than writing free-form text messages, structured logs capture events as objects with defined properties—timestamp, severity level, source, message, and contextual metadata. JSON has emerged as the preferred format for structured logs due to its universal parseability, hierarchical capability, and human readability, though XML, CSV, and custom formats serve specific requirements.

function Write-StructuredLog {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Message,
        
        [ValidateSet('Debug', 'Info', 'Warning', 'Error', 'Critical')]
        [string]$Severity = 'Info',
        
        [hashtable]$Context = @{},
        
        [string]$LogPath = "$env:ProgramData\MyScript\Logs\application.log"
    )
    
    # Ensure log directory exists
    $logDir = Split-Path -Path $LogPath -Parent
    if (-not (Test-Path -Path $logDir)) {
        New-Item -Path $logDir -ItemType Directory -Force | Out-Null
    }
    
    # Build structured log entry
    $logEntry = [ordered]@{
        Timestamp = Get-Date -Format "yyyy-MM-ddTHH:mm:ss.fffZ"
        Severity = $Severity
        Message = $Message
        ScriptName = $MyInvocation.ScriptName
        ScriptLine = $MyInvocation.ScriptLineNumber
        User = $env:USERNAME
        Computer = $env:COMPUTERNAME
        ProcessId = $PID
        Context = $Context
    }
    
    # Convert to JSON and append to log file
    $logJson = $logEntry | ConvertTo-Json -Compress
    Add-Content -Path $LogPath -Value $logJson -Encoding UTF8
    
    # Also write to appropriate stream for immediate visibility
    switch ($Severity) {
        'Debug'    { Write-Debug $Message }
        'Info'     { Write-Information $Message }
        'Warning'  { Write-Warning $Message }
        'Error'    { Write-Error $Message }
        'Critical' { Write-Error $Message }
    }
}

# Usage example with rich context
try {
    $result = Invoke-DatabaseQuery -Query $query -Database $dbName
    Write-StructuredLog -Message "Database query executed successfully" -Severity Info -Context @{
        Database = $dbName
        RowsAffected = $result.RowsAffected
        ExecutionTime = $result.ExecutionTime
        QueryHash = (Get-StringHash $query)
    }
}
catch {
    Write-StructuredLog -Message "Database query failed" -Severity Error -Context @{
        Database = $dbName
        Query = $query
        ErrorType = $_.Exception.GetType().FullName
        ErrorMessage = $_.Exception.Message
        StackTrace = $_.ScriptStackTrace
    }
    throw
}

"Logs are the difference between knowing something went wrong and understanding why it went wrong, when it started, what was affected, and how to prevent it from happening again."

Log Rotation and Maintenance

Unmanaged log files grow indefinitely, consuming disk space and degrading performance as file sizes reach gigabytes. Implementing log rotation creates a sustainable logging practice by archiving old logs and starting fresh files based on size or time thresholds. A robust rotation strategy preserves recent logs for immediate troubleshooting while compressing or deleting older logs according to retention policies, balancing diagnostic capability against storage costs.

function Invoke-LogRotation {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$LogPath,
        
        [int]$MaxFileSizeMB = 10,
        
        [int]$MaxArchiveCount = 10,
        
        [switch]$CompressArchives
    )
    
    if (-not (Test-Path -Path $LogPath)) {
        return  # No log file to rotate
    }
    
    $logFile = Get-Item -Path $LogPath
    $logSizeMB = $logFile.Length / 1MB
    
    if ($logSizeMB -lt $MaxFileSizeMB) {
        return  # File hasn't reached rotation threshold
    }
    
    # Generate archive filename with timestamp
    $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
    $archivePath = Join-Path -Path $logFile.DirectoryName -ChildPath "$($logFile.BaseName)-$timestamp$($logFile.Extension)"
    
    # Move current log to archive
    Move-Item -Path $LogPath -Destination $archivePath -Force
    
    # Compress archive if requested
    if ($CompressArchives) {
        $zipPath = "$archivePath.zip"
        Compress-Archive -Path $archivePath -DestinationPath $zipPath
        Remove-Item -Path $archivePath -Force
        $archivePath = $zipPath
    }
    
    # Remove old archives exceeding retention count
    $archivePattern = "$($logFile.BaseName)-*$($logFile.Extension)*"
    $archives = Get-ChildItem -Path $logFile.DirectoryName -Filter $archivePattern |
        Sort-Object -Property LastWriteTime -Descending
    
    if ($archives.Count -gt $MaxArchiveCount) {
        $archives | Select-Object -Skip $MaxArchiveCount | Remove-Item -Force
    }
    
    Write-Verbose "Log rotated: $archivePath (retained $MaxArchiveCount archives)"
}

# Implement rotation check at script start
$logPath = "$env:ProgramData\MyScript\Logs\application.log"
Invoke-LogRotation -LogPath $logPath -MaxFileSizeMB 10 -MaxArchiveCount 10 -CompressArchives

Integration with Windows Event Log

Windows Event Log provides enterprise-grade logging infrastructure with built-in management, remote collection, and integration with monitoring tools. Writing to Event Log makes your PowerShell scripts visible to existing operational monitoring systems, enables centralized log collection via Windows Event Forwarding, and leverages Event Log's native filtering and querying capabilities. However, Event Log requires administrative privileges to create custom event sources and imposes structure on log entries that may not suit all scenarios.

# One-time setup (requires administrative privileges)
# Create custom event source for your application
if (-not [System.Diagnostics.EventLog]::SourceExists("MyPowerShellScript")) {
    New-EventLog -LogName Application -Source "MyPowerShellScript"
}

function Write-EventLogEntry {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Message,
        
        [ValidateSet('Information', 'Warning', 'Error')]
        [string]$EntryType = 'Information',
        
        [int]$EventId = 1000,
        
        [string]$Source = "MyPowerShellScript"
    )
    
    try {
        Write-EventLog -LogName Application `
                       -Source $Source `
                       -EntryType $EntryType `
                       -EventId $EventId `
                       -Message $Message
    }
    catch {
        # Fallback if Event Log writing fails
        Write-Warning "Failed to write to Event Log: $($_.Exception.Message)"
        Write-Warning "Original message: $Message"
    }
}

# Usage in error handling
try {
    Invoke-CriticalOperation
}
catch {
    $errorMessage = @"
Critical operation failed
Error: $($_.Exception.Message)
User: $env:USERNAME
Computer: $env:COMPUTERNAME
Script: $($MyInvocation.ScriptName)
Line: $($MyInvocation.ScriptLineNumber)
"@
    
    Write-EventLogEntry -Message $errorMessage -EntryType Error -EventId 5001
    throw
}

Advanced Error Recovery Patterns

Beyond simply catching errors, sophisticated scripts implement recovery strategies that attempt to overcome transient failures, degrade gracefully when full functionality isn't available, and maintain consistent state even through error conditions. Retry logic with exponential backoff handles temporary resource unavailability, circuit breaker patterns prevent cascading failures in distributed systems, and compensating transactions roll back partial operations when complete success isn't achievable. These patterns transform brittle scripts that fail on first error into resilient automation that adapts to real-world operational conditions.

Retry Logic with Exponential Backoff

Many failures—network timeouts, resource locks, rate limiting—are transient and resolve if you simply wait and try again. Implementing retry logic with exponential backoff automatically recovers from these temporary conditions without requiring manual intervention. The exponential backoff strategy progressively increases wait time between retries, preventing your script from hammering a struggling resource while giving adequate time for transient conditions to clear.

function Invoke-WithRetry {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [scriptblock]$ScriptBlock,
        
        [int]$MaxAttempts = 3,
        
        [int]$InitialDelaySeconds = 2,
        
        [double]$BackoffMultiplier = 2.0,
        
        [Type[]]$RetryableExceptions = @([System.Net.WebException], [System.TimeoutException])
    )
    
    $attempt = 1
    $delay = $InitialDelaySeconds
    
    while ($attempt -le $MaxAttempts) {
        try {
            Write-Verbose "Attempt $attempt of $MaxAttempts"
            return & $ScriptBlock
        }
        catch {
            $isRetryable = $false
            foreach ($exceptionType in $RetryableExceptions) {
                if ($_.Exception -is $exceptionType) {
                    $isRetryable = $true
                    break
                }
            }
            
            if (-not $isRetryable -or $attempt -eq $MaxAttempts) {
                Write-Error "Operation failed after $attempt attempts: $($_.Exception.Message)"
                throw
            }
            
            Write-Warning "Attempt $attempt failed: $($_.Exception.Message). Retrying in $delay seconds..."
            Start-Sleep -Seconds $delay
            
            $attempt++
            $delay = [math]::Min($delay * $BackoffMultiplier, 60)  # Cap at 60 seconds
        }
    }
}

# Usage example
$data = Invoke-WithRetry -MaxAttempts 5 -InitialDelaySeconds 2 -ScriptBlock {
    Invoke-RestMethod -Uri $apiEndpoint -Method Get -Headers $headers -ErrorAction Stop
}

"Resilience isn't about preventing failures—it's about ensuring your system continues to deliver value even when individual components fail, and recovers gracefully when conditions improve."

Circuit Breaker Pattern

When a dependency consistently fails, repeatedly attempting to use it wastes resources and delays error detection. The circuit breaker pattern monitors failure rates and temporarily stops calling a failing dependency, allowing it time to recover while immediately returning errors to callers. After a timeout period, the circuit breaker allows test requests through, and if they succeed, resumes normal operation. This pattern prevents cascading failures and provides fast failure feedback when dependencies are unavailable.

class CircuitBreaker {
    [string]$Name
    [int]$FailureThreshold
    [int]$TimeoutSeconds
    [datetime]$LastFailureTime
    [int]$ConsecutiveFailures
    [string]$State  # Closed, Open, HalfOpen
    
    CircuitBreaker([string]$name, [int]$failureThreshold, [int]$timeoutSeconds) {
        $this.Name = $name
        $this.FailureThreshold = $failureThreshold
        $this.TimeoutSeconds = $timeoutSeconds
        $this.ConsecutiveFailures = 0
        $this.State = 'Closed'
    }
    
    [object] Execute([scriptblock]$operation) {
        if ($this.State -eq 'Open') {
            $timeSinceFailure = (Get-Date) - $this.LastFailureTime
            if ($timeSinceFailure.TotalSeconds -gt $this.TimeoutSeconds) {
                Write-Verbose "Circuit breaker $($this.Name) entering half-open state"
                $this.State = 'HalfOpen'
            }
            else {
                throw "Circuit breaker $($this.Name) is open. Dependency unavailable."
            }
        }
        
        try {
            $result = & $operation
            $this.OnSuccess()
            return $result
        }
        catch {
            $this.OnFailure()
            throw
        }
    }
    
    [void] OnSuccess() {
        $this.ConsecutiveFailures = 0
        if ($this.State -eq 'HalfOpen') {
            Write-Verbose "Circuit breaker $($this.Name) closing after successful test"
            $this.State = 'Closed'
        }
    }
    
    [void] OnFailure() {
        $this.ConsecutiveFailures++
        $this.LastFailureTime = Get-Date
        
        if ($this.ConsecutiveFailures -ge $this.FailureThreshold) {
            Write-Warning "Circuit breaker $($this.Name) opening after $($this.ConsecutiveFailures) consecutive failures"
            $this.State = 'Open'
        }
    }
}

# Usage example
$apiCircuitBreaker = [CircuitBreaker]::new("ExternalAPI", 3, 30)

try {
    $response = $apiCircuitBreaker.Execute({
        Invoke-RestMethod -Uri $apiEndpoint -ErrorAction Stop
    })
}
catch {
    Write-Error "API call failed: $($_.Exception.Message)"
    # Implement fallback logic or graceful degradation
}

Performance Considerations in Error Handling

Error handling mechanisms introduce overhead that can significantly impact script performance, particularly in tight loops or high-frequency operations. Try-catch blocks incur minimal cost during normal execution but impose substantial overhead when exceptions are thrown and caught. Excessive logging, especially to slow destinations like network shares or databases, can dominate execution time. Understanding these performance implications enables you to design error handling strategies that provide necessary protection without creating performance bottlenecks.

The performance cost of try-catch is negligible when no exceptions occur—the JIT compiler optimizes the happy path efficiently. However, throwing and catching exceptions is expensive because it involves capturing the call stack, creating exception objects, and unwinding the stack to find handlers. This cost makes exceptions unsuitable for controlling normal program flow or handling expected conditions that occur frequently. Instead, use conditional logic to check for expected conditions and reserve exceptions for truly exceptional circumstances that warrant the diagnostic overhead.

• ⚡ Minimize try-catch scope to only code that genuinely needs protection, avoiding wrapping entire scripts unnecessarily
• 🎯 Use -ErrorAction SilentlyContinue with -ErrorVariable for expected errors instead of try-catch when appropriate
• 📊 Implement conditional logging that writes detailed logs only when errors occur or verbose mode is enabled
• 💾 Buffer log writes to reduce I/O operations, flushing batches periodically rather than writing each entry immediately
• 🔄 Consider asynchronous logging for high-throughput scenarios where logging shouldn't block script execution

"The best error handling is invisible during normal operation—providing comprehensive protection without imposing perceptible overhead, then delivering rich diagnostic information the instant something goes wrong."

Testing and Validating Error Handling

Error handling code that never executes is untested code, and untested code is broken code waiting to reveal itself at the worst possible moment. Deliberately testing error paths ensures your error handling actually works when needed, validates that errors are logged correctly, confirms recovery mechanisms function as designed, and verifies that cleanup code executes even during failures. Pester, PowerShell's testing framework, provides capabilities specifically designed for testing error conditions, including mocking to simulate failures and assertion commands that verify expected exceptions occur.

Describe "Database Connection Error Handling" {
    BeforeAll {
        # Setup test environment
        $script:logPath = "$TestDrive\test.log"
    }
    
    Context "When database is unavailable" {
        It "Should throw appropriate exception" {
            Mock Connect-Database { throw [System.Data.SqlClient.SqlException]::new() }
            
            { Initialize-DatabaseConnection -ConnectionString $testConnectionString } |
                Should -Throw -ExceptionType ([System.Data.SqlClient.SqlException])
        }
        
        It "Should log connection failure" {
            Mock Connect-Database { throw [System.Data.SqlClient.SqlException]::new() }
            Mock Write-StructuredLog { }
            
            try {
                Initialize-DatabaseConnection -ConnectionString $testConnectionString
            }
            catch { }
            
            Should -Invoke Write-StructuredLog -Times 1 -ParameterFilter {
                $Severity -eq 'Error' -and $Message -like '*connection failed*'
            }
        }
        
        It "Should execute cleanup in finally block" {
            Mock Connect-Database { throw [System.Data.SqlClient.SqlException]::new() }
            $script:cleanupExecuted = $false
            
            try {
                try {
                    Connect-Database -ConnectionString $testConnectionString
                }
                finally {
                    $script:cleanupExecuted = $true
                }
            }
            catch { }
            
            $script:cleanupExecuted | Should -Be $true
        }
    }
    
    Context "When retry logic is triggered" {
        It "Should retry specified number of times" {
            Mock Invoke-DatabaseQuery { throw [System.TimeoutException]::new() }
            
            try {
                Invoke-WithRetry -MaxAttempts 3 -ScriptBlock {
                    Invoke-DatabaseQuery -Query $testQuery
                }
            }
            catch { }
            
            Should -Invoke Invoke-DatabaseQuery -Times 3
        }
        
        It "Should succeed on subsequent attempt" {
            $script:attemptCount = 0
            Mock Invoke-DatabaseQuery {
                $script:attemptCount++
                if ($script:attemptCount -lt 3) {
                    throw [System.TimeoutException]::new()
                }
                return @{ Success = $true }
            }
            
            $result = Invoke-WithRetry -MaxAttempts 3 -ScriptBlock {
                Invoke-DatabaseQuery -Query $testQuery
            }
            
            $result.Success | Should -Be $true
            $script:attemptCount | Should -Be 3
        }
    }
}

Integration with Monitoring and Alerting Systems

Error handling and logging reach their full potential when integrated with operational monitoring systems that provide real-time visibility, automated alerting, and trend analysis. Rather than requiring administrators to manually review logs, integration with monitoring platforms enables proactive detection of issues, automated escalation of critical errors, and dashboards that visualize error rates and patterns. Whether you're using commercial solutions like Splunk or SCOM, open-source tools like ELK stack or Grafana, or cloud-native services like Azure Monitor or AWS CloudWatch, PowerShell can feed error data into these systems for comprehensive operational visibility.

function Send-MonitoringEvent {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Message,
        
        [ValidateSet('Info', 'Warning', 'Error', 'Critical')]
        [string]$Severity = 'Info',
        
        [hashtable]$Tags = @{},
        
        [hashtable]$Metrics = @{},
        
        [string]$MonitoringEndpoint = $env:MONITORING_ENDPOINT
    )
    
    $event = @{
        timestamp = (Get-Date).ToUniversalTime().ToString("o")
        severity = $Severity.ToLower()
        message = $Message
        source = @{
            script = $MyInvocation.ScriptName
            computer = $env:COMPUTERNAME
            user = $env:USERNAME
        }
        tags = $Tags
        metrics = $Metrics
    }
    
    try {
        $json = $event | ConvertTo-Json -Depth 10 -Compress
        Invoke-RestMethod -Uri $MonitoringEndpoint `
                         -Method Post `
                         -Body $json `
                         -ContentType "application/json" `
                         -TimeoutSec 5 `
                         -ErrorAction Stop
    }
    catch {
        # Fallback logging if monitoring system is unavailable
        Write-Warning "Failed to send monitoring event: $($_.Exception.Message)"
        Write-StructuredLog -Message $Message -Severity $Severity -Context $Tags
    }
}

# Usage in error handling with rich context
try {
    $result = Invoke-DataProcessing -InputFile $inputPath
    
    Send-MonitoringEvent -Message "Data processing completed" `
                        -Severity Info `
                        -Tags @{ 
                            operation = "data_processing"
                            input_file = $inputPath
                        } `
                        -Metrics @{
                            records_processed = $result.RecordCount
                            duration_seconds = $result.Duration.TotalSeconds
                        }
}
catch {
    Send-MonitoringEvent -Message "Data processing failed: $($_.Exception.Message)" `
                        -Severity Error `
                        -Tags @{
                            operation = "data_processing"
                            input_file = $inputPath
                            error_type = $_.Exception.GetType().Name
                        }
    throw
}

Security Considerations in Logging

Logging creates permanent records that may contain sensitive information—credentials, personal data, proprietary business information, or security-relevant details that could aid attackers. Implementing secure logging practices prevents your error handling from becoming a security vulnerability. Never log credentials, API keys, or passwords, even in encrypted form. Sanitize or redact personal information according to privacy regulations. Control access to log files using appropriate file system permissions. Consider the security implications of log retention and implement secure deletion of aged logs. When logging to remote systems, ensure transport encryption and authentication.

function Write-SecureLog {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)]
        [string]$Message,
        
        [hashtable]$Context = @{},
        
        [string[]]$SensitiveKeys = @('password', 'credential', 'apikey', 'secret', 'token')
    )
    
    # Sanitize context to remove sensitive information
    $sanitizedContext = @{}
    foreach ($key in $Context.Keys) {
        $isSensitive = $false
        foreach ($sensitiveKey in $SensitiveKeys) {
            if ($key -like "*$sensitiveKey*") {
                $isSensitive = $true
                break
            }
        }
        
        if ($isSensitive) {
            $sanitizedContext[$key] = "[REDACTED]"
        }
        else {
            # Still sanitize string values that might contain credentials
            $value = $Context[$key]
            if ($value -is [string] -and $value.Length -gt 20) {
                # Check for patterns that look like credentials
                if ($value -match '(?i)(password|key|token|secret)\s*[:=]\s*\S+') {
                    $sanitizedContext[$key] = "[REDACTED - Pattern Match]"
                }
                else {
                    $sanitizedContext[$key] = $value
                }
            }
            else {
                $sanitizedContext[$key] = $value
            }
        }
    }
    
    Write-StructuredLog -Message $Message -Context $sanitizedContext
}

# Usage example
try {
    $connection = Connect-Service -Credential $credential -Endpoint $endpoint
}
catch {
    # Logs error without exposing credential
    Write-SecureLog -Message "Service connection failed" -Context @{
        Endpoint = $endpoint
        Credential = $credential  # Will be automatically redacted
        ErrorType = $_.Exception.GetType().Name
    }
}

"Security and observability must coexist—comprehensive logging provides the visibility you need to detect and respond to security incidents, but only if implemented with safeguards that prevent logs themselves from becoming attack vectors or compliance violations."

How do I decide between using try-catch versus trap for error handling in my PowerShell scripts?

Choose try-catch for explicit, localized error handling where you need different responses for different error types within specific code sections. Try-catch provides clearer code structure, better IDE support, and more precise control over which operations are protected. Use trap when you need consistent error handling across an entire function or script scope without wrapping every operation in try blocks, or when retrofitting error handling into existing scripts. Try-catch is generally preferred for new development due to its explicitness and maintainability, while trap serves well for establishing script-wide error policies.

What's the performance impact of extensive error handling and logging in production scripts?

Try-catch blocks have negligible performance impact during normal execution when no exceptions occur. The overhead appears when exceptions are actually thrown and caught, making exceptions unsuitable for controlling normal program flow. Logging performance depends primarily on the destination—writing to local files is fast, while network logging or database writes introduce latency. Mitigate performance impact by minimizing try-catch scope to only necessary code, using conditional logging that writes detailed information only when needed, buffering log writes to reduce I/O operations, and considering asynchronous logging patterns for high-throughput scenarios. Measure actual performance in your specific context rather than prematurely optimizing.

How can I ensure my error handling code actually works when errors occur?

Implement comprehensive testing using Pester to deliberately trigger error conditions and verify your handling code executes correctly. Test that expected exceptions are thrown, error messages are logged with appropriate detail, retry logic attempts the correct number of times, cleanup code in finally blocks executes even during failures, and recovery mechanisms successfully restore operational state. Use mocking to simulate various failure scenarios including network timeouts, access denied conditions, and resource unavailability. Include error path testing in your continuous integration pipeline to catch regressions. Remember that untested error handling is essentially untested code that will fail when you need it most.

What information should I include in error logs to make troubleshooting effective?

Effective error logs capture the complete context necessary to understand and reproduce the issue. Include the error message and exception type, the exact operation being attempted when the error occurred, relevant input parameters or data being processed, environmental context like computer name, user account, and timestamp, the complete call stack showing the error's origin, and any relevant state information that might explain the failure. Use structured logging formats like JSON that preserve this information in a parseable format. Balance detail against security by sanitizing sensitive information like credentials. The goal is enabling someone unfamiliar with the code to understand what happened, why it happened, and how to fix it without access to the original developer.

Should I use Write-Error, throw, or both in my error handling code?

Use Write-Error to report non-terminating errors that provide information but allow the script to continue, such as processing failures for individual items in a batch where you want to report each failure but continue processing remaining items. Use throw to generate terminating errors that halt execution and require explicit handling, appropriate for critical failures where continuing would be dangerous or meaningless. Often you'll use both—Write-Error or Write-StructuredLog to record detailed error information for diagnostics, followed by throw to escalate the error to calling code that can make recovery decisions. In catch blocks, consider whether to handle the error completely, log and re-throw to allow higher-level handling, or wrap in a new exception with additional context.

How do I implement log rotation without losing important diagnostic information?

Implement size-based or time-based rotation that archives logs before they become unwieldy while preserving recent history. Archive old logs with timestamps in filenames, compress archives to save space, and retain a configurable number of archives based on your troubleshooting and compliance requirements. Implement rotation checks at script startup or periodically during long-running scripts. For critical systems, consider shipping logs to centralized collection systems before rotation so nothing is lost even if local archives are deleted. Balance retention duration against storage costs and regulatory requirements. Document your retention policy and ensure operations teams understand where to find archived logs when troubleshooting historical issues.