PowerShell error handling techniques

Effective error handling is crucial for developing robust PowerShell scripts. Without it, your script might halt unexpectedly, or even worse, continue in an undesired state. This article provides a deep dive into different techniques for handling and debugging errors in PowerShell.

Understanding PowerShell errors

In PowerShell, errors come in two flavors:

Terminating errors: These are serious errors that halt the execution of your script, such as a missing cmdlet or a missing required parameter.
Non-terminating errors: These errors don’t stop the execution of the script. They usually occur while processing a collection of items when an error in one item shouldn’t halt the whole operation.

# A terminating error
Get-Command -Name NonExistentCmdlet

# A non-terminating error
Get-ChildItem -Path C:\NonExistentPath

Error handling with Try/Catch/Finally

Try/Catch/Finally is a powerful error handling mechanism in PowerShell. Code in the Try block is executed, and if an error occurs, execution is transferred to the Catch block. The Finally block runs irrespective of whether an error occurred or not, making it ideal for cleanup operations.

try {
    # Code that might throw an error
    Get-Content -Path "C:\NonExistentFile.txt"
}
catch {
    # Handle the error
    Write-Error "An error occurred: $_"
}
finally {
    # Cleanup code
    Write-Output "End of error handling"
}

Converting non-terminating to terminating errors

To catch a non-terminating error with a Try/Catch block, you must convert it into a terminating error. This can be done using the -ErrorAction Stop parameter.

try {
    # Convert non-terminating error to terminating
    Get-ChildItem -Path C:\NonExistentPath -ErrorAction Stop
}
catch {
    Write-Error "An error occurred: $_"
}

Error variables

PowerShell provides the automatic variable $Error, which is an array that stores recent error objects. $Error[0] represents the most recent error.

# Cause an error
Get-ChildItem -Path C:\NonExistentPath

# Display the most recent error
Write-Output $Error[0]

You can also use -ErrorVariable parameter to store error details in a custom variable.

# Cause an error and store details in a custom variable
Get-ChildItem -Path C:\NonExistentPath -ErrorVariable MyError

# Display the custom error variable
Write-Output $MyError

Using ErrorActionPreference

$ErrorActionPreference controls how PowerShell responds to non-terminating errors. You can set it to Stop to treat all errors as terminating errors.

$ErrorActionPreference = "Stop"
Get-ChildItem -Path C:\NonExistentPath

Best practices

Use specific catch blocks: You can catch specific exceptions, which is useful for handling different types of errors in different ways.
Use the Throw keyword: Throw allows you to generate a terminating error. It’s useful when you want to halt execution due to an unexpected state in your script.
Use Write-Error for non-terminating errors: When you want to report an error but not halt the execution, Write-Error is the cmdlet to use.

Conclusion

Use specific catch blocks: You can catch specific exceptions, which is useful for handling different types of errors in different ways.
Use the Throw keyword: Throw allows you to generate a terminating error. It’s useful when you want to halt execution due to an unexpected state in your script.
Use Write-Error for non-terminating errors: When you want to report an error but not halt the execution, Write-Error is the cmdlet to use.

More resources

about_Try_Catch_Finally | learn.microsoft.com
Everything you wanted to know about exceptions | learn.microsoft.com
The Big Book of PowerShell Error Handling | leanpub.com