PowerShell Error Handling Mastery: Try/Catch/Finally and ErrorActionPreference (2026)

The first thing that surprises a C# developer writing PowerShell is that try/catch often does nothing. Get-Item C:\does-not-exist writes a red error to the console but the script keeps running, and the catch block never fires. That is by design — PowerShell distinguishes terminating from non-terminating errors, and most cmdlets default to non-terminating so a long pipeline can survive one bad item. Once you understand the model, controlling it is easy.

This guide covers the full PowerShell error story: terminating vs non-terminating, $ErrorActionPreference, the -ErrorAction parameter, try/catch/finally, typed catches, $Error, the trap statement, and the patterns you should use in production. Free PDF cheat sheet at the bottom.

Terminating vs non-terminating errors

A terminating error halts the current pipeline and is catchable by try/catch. A non-terminating error writes to the error stream but does not stop execution. Most cmdlets emit non-terminating errors by default — that is what lets Remove-Item *.log keep deleting the rest of the files even if one of them is locked.

To make a non-terminating error terminating, set -ErrorAction Stop on the cmdlet:

# Non-terminating - try/catch does nothing
try { Get-Item C:\does-not-exist }
catch { Write-Host "caught" }
# Output: red error from Get-Item, no "caught"

# Terminating - try/catch fires
try { Get-Item C:\does-not-exist -ErrorAction Stop }
catch { Write-Host "caught" }
# Output: "caught"

-ErrorAction and $ErrorActionPreference

-ErrorAction is a common parameter available on every advanced cmdlet. The values:

• Continue — write the error and keep going (default)
• Stop — promote to terminating, raise an exception
• SilentlyContinue — suppress the error message and keep going
• Ignore — suppress AND do not add to $Error
• Inquire — prompt the user

$ErrorActionPreference sets the default for the current scope. Setting it to Stop at the top of a script is one of the highest-value things you can do — every non-terminating error becomes catchable, and surprises become impossible:

$ErrorActionPreference = 'Stop'
Set-StrictMode -Version Latest

try {
    Get-Item C:\maybe-here     # would have been non-terminating
    Remove-Item C:\file.txt    # same
}
catch {
    Write-Host "Failed: $_" -ForegroundColor Red
    exit 1
}

try / catch / finally

Standard structure:

try {
    # Code that might fail
}
catch {
    # Handle the error - $_ or $PSItem is the ErrorRecord
}
finally {
    # ALWAYS runs - cleanup
}

Inside catch, the special variable $_ (also $PSItem) is the ErrorRecord. The most useful properties:

catch {
    $_.Exception.Message        # The human-readable message
    $_.Exception.GetType()      # The .NET exception type
    $_.ScriptStackTrace         # Where it happened
    $_.InvocationInfo.Line      # The actual offending line
    $_.CategoryInfo.Category    # PowerShell error category
    $_.FullyQualifiedErrorId    # Unique error identifier
}

Catching specific exception types

Multiple catch blocks let you handle different exception types differently — same as in C#:

try {
    $r = Invoke-RestMethod $url -ErrorAction Stop
}
catch [System.Net.WebException] {
    Write-Host "Network error: $($_.Exception.Message)"
}
catch [System.IO.FileNotFoundException] {
    Write-Host "Missing file: $($_.Exception.Message)"
}
catch {
    # Generic fallback
    Write-Host "Unexpected: $($_.Exception.GetType().FullName) - $($_.Exception.Message)"
    throw  # re-raise
}

Find the right type to catch by triggering the error once and inspecting $Error[0].Exception.GetType().FullName.

The $Error variable

$Error is an automatic ArrayList that holds the last 256 errors (configurable via $MaximumErrorCount) — even non-terminating ones, and even ones suppressed with SilentlyContinue (but not Ignore). The most recent error is $Error[0].

Get-Item C:\nope -ErrorAction SilentlyContinue
$Error[0].Exception          # Inspect even though it was silenced

$Error.Clear()               # Reset the buffer

-ErrorVariable

The -ErrorVariable common parameter captures the errors of a single command into a named variable, without affecting $Error:

Get-ChildItem C:\maybe -Recurse -ErrorAction SilentlyContinue -ErrorVariable scanErrors
if ($scanErrors) {
    $scanErrors | ForEach-Object {
        Write-Host "Could not scan: $($_.TargetObject)" -ForegroundColor Yellow
    }
}

Useful when you genuinely want to keep going on most failures but log the ones you saw.

The trap statement

trap is a script-level fallback. It catches any terminating error in the current scope and runs the trap body. Combined with continue or break you can decide whether to keep going or unwind:

trap {
    Write-Host "Trapped: $_" -ForegroundColor Red
    continue   # keep running the script
}

# Anywhere in this scope, terminating errors hit the trap
Get-Item C:\nope -ErrorAction Stop
Write-Host "still here"

In modern code, prefer try/catch for clarity. trap is occasionally useful as a script-wide safety net at the very top.

throw and Write-Error

To raise a terminating error from your own code, use throw:

throw "Cannot continue: configuration file is missing"

# Better - throw a typed exception
throw [System.IO.FileNotFoundException]::new("Config not found", $cfgPath)

For non-terminating errors (which a caller can choose to escalate with -ErrorAction Stop), use Write-Error:

Write-Error -Message "Skipped $name: not eligible" `
            -Category InvalidOperation `
            -ErrorId 'NotEligible' `
            -TargetObject $name

Real-world patterns

The script-top safety block

[CmdletBinding()]
param()

$ErrorActionPreference = 'Stop'
Set-StrictMode -Version Latest

try {
    # Whole script body here
}
catch {
    Write-Error "FAILED: $($_.Exception.Message)" -ErrorAction Continue
    Write-Error "AT: $($_.ScriptStackTrace)" -ErrorAction Continue
    exit 1
}
finally {
    # Always-run cleanup
}

Per-item resilience

foreach ($item in $items) {
    try {
        Process-Item $item -ErrorAction Stop
    } catch {
        Write-Warning "Item $($item.Id) failed: $($_.Exception.Message)"
        $failed += $item
        continue
    }
}
Write-Host "$($failed.Count) of $($items.Count) failed"

Resource cleanup with finally

$conn = $null
try {
    $conn = [System.Data.SqlClient.SqlConnection]::new($cs)
    $conn.Open()
    # ... query ...
}
catch {
    Write-Error "DB error: $($_.Exception.Message)"
    throw
}
finally {
    if ($conn) { $conn.Dispose() }
}

Cheat sheet

Every flag, every variable, the patterns above on a single PDF: PowerShell Error Handling Cheat Sheet.

FAQ

Related reading

• Error Handling Cheat Sheet (PDF)
• Advanced Functions Guide
• Dargslan Tech Blog