PowerShell Error Handling Explained with Examples

Whether you’re writing scripts to automate everyday tasks or building complex tools in Windows, PowerShell is an indispensable companion for system administrators and developers. One of the most critical aspects of scripting in any language is error handling. Without it, scripts can fail silently, cause unintended consequences, or stop execution unexpectedly.

In this article, we’ll explore PowerShell error handling in depth. You’ll learn the different types of errors, how they can be managed, and best practices for making your scripts more robust and reliable.

Understanding PowerShell Errors

There are two primary types of errors in PowerShell:

Terminating errors: These halt the execution of the script immediately. An example would be trying to access a file that doesn’t exist when the command is instructed to stop on error.
Non-terminating errors: These errors report issues but allow the script to continue. Most cmdlets generate this type of error by default.

When you’re working with PowerShell, understanding which type of error you’re dealing with is key to effectively handling those errors.

Error Action Preferences

PowerShell has a special variable called $ErrorActionPreference that determines how it handles non-terminating errors.

It can take several different values:

Continue (default): Displays the error and continues executing the script.
Stop: Treats non-terminating errors as terminating ones.
SilentlyContinue: Suppresses the error message and continues execution.
Inquire: Prompts the user to decide whether to continue.
Ignore: Ignores the error without displaying or logging it.

You can change the global behavior by setting $ErrorActionPreference, or override it on a per-command basis using the -ErrorAction parameter. For example:

Get-Item "C:\nonexistentfile.txt" -ErrorAction SilentlyContinue

This line will not output an error even if the file doesn’t exist.

Using Try, Catch, and Finally

PowerShell uses structured error handling with try, catch, and finally blocks, similar to other languages like C# and JavaScript. This mechanism is most effective for dealing with terminating errors.

Here’s a basic example:

try {
    # Code that might throw an error
    Remove-Item "C:\importantfile.txt" -ErrorAction Stop
}
catch {
    Write-Host "An error occurred:"
    Write-Host $_.Exception.Message
}
finally {
    Write-Host "Cleanup or follow-up actions go here."
}

In this example:

try runs the risky command.
catch handles the error using the automatic $_ variable to get error details.
finally runs regardless of success or error, ideal for releasing resources or logging.

Note that only terminating errors trigger the catch block. If you’re working with commands that generate non-terminating errors, use -ErrorAction Stop to convert them into terminating errors.

Accessing Error Details

Within a catch block, you gain access to an error object that provides a wealth of diagnostic information.

catch {
    $errorInfo = $_
    Write-Host "Message: $($errorInfo.Exception.Message)"
    Write-Host "Category: $($errorInfo.CategoryInfo.Category)"
    Write-Host "Line Number: $($errorInfo.InvocationInfo.ScriptLineNumber)"
}

This lets you create detailed error logs and reports, making debugging dramatically easier.

Using Multiple Catch Blocks

Just like C#, PowerShell supports multiple catch blocks for handling specific error types. For example:

try {
    # Risky operation
    Get-Content "C:\nonexistentfile.txt" -ErrorAction Stop
}
catch [System.IO.FileNotFoundException] {
    Write-Host "File not found. Check the filepath."
}
catch {
    Write-Host "A generic error occurred."
}

By using typed catch blocks, you can tailor error handling responses to specific situations and types, rather than relying on a blanket response.

The $Error Variable

PowerShell stores recent errors in an automatic variable called $Error. This is an array, and the most recent error is at index 0.

Get-Item "C:\nonexistentfile.txt"
Write-Output $Error[0]

Be cautious when using this in scripts that run multiple commands, as it may not always reflect the most recent error in the specific way you expect.

Error Handling with Functions

Error handling becomes vital inside functions, especially when building reusable tools or scripts. Let’s look at an example function with error handling baked in:

function Read-FileContent {
    param([string]$Path)

    try {
        $content = Get-Content -Path $Path -ErrorAction Stop
        return $content
    }
    catch {
        Write-Host "Failed to read file: $($Path)"
        Write-Host $_.Exception.Message
    }
}

This function attempts to read a file’s content and properly handles any issues such as the file not being found or inaccessible.

Common Error Handling Pitfalls

Even experienced scripters sometimes fall into traps when handling errors. Here are some common mistakes to avoid:

Forgetting to use -ErrorAction Stop with non-terminating errors, meaning your catch blocks won’t execute.
Ignoring the scope of error variables such as $Error inside nested functions or scopes.
Overusing SilentlyContinue and inadvertently hiding important failures.

To write robust scripts, always make sure you’re deliberate and precise about how you handle possible failures.

Writing Your Own Exceptions

Occasionally, you’ll want to generate your own errors to simulate failures or enforce conditions. PowerShell has a throw keyword for this.

Here’s a quick example:

function Check-Port {
    param([int]$Port)

    if ($Port -lt 1 -or $Port -gt 65535) {
        throw "Port number $Port is out of valid range (1-65535)."
    }

    Write-Host "Port $Port is valid."
}

Now, when you pass an invalid port, the function will raise a terminating error, which you can catch using structured error blocks.

Putting It All Together

Here’s a final consolidated example to demonstrate everything we’ve covered so far:

function Backup-File {
    param([string]$SourcePath, [string]$DestinationPath)

    try {
        if (-not (Test-Path $SourcePath)) {
            throw "Source file does not exist: $SourcePath"
        }

        Copy-Item -Path $SourcePath -Destination $DestinationPath -ErrorAction Stop
        Write-Host "Backup completed successfully."
    }
    catch {
        Write-Host "Backup failed:"
        Write-Host $_.Exception.Message
    }
    finally {
        Write-Host "Backup attempt finished at $(Get-Date)"
    }
}

This function checks for file existence, handles potential copy errors, and logs the status regardless of success or failure. You could easily schedule this script or include it in a larger automation framework for safe and transparent file backup operations.

Conclusion

Effective error handling is foundational to writing robust, maintainable, and user-friendly PowerShell scripts. By learning to control error output, harness trap mechanisms like try/catch/finally, and avoid common pitfalls, you’re not just preventing script crashes—you’re actively boosting the reliability of your automation processes.

The next time your script attempts something risky, don’t leave it to chance. Build a safety net with smart error handling, and your future self will thank you.

WP Sticky