Unlike other programming languages, the PowerShell scripting language has two types of error scenarios: terminating and non-terminating. Both of these types of errors are "bad," but by classifying them differently, the scripter can handle them differently. This distinction is important if you want to stop or exit a PowerShell script when it errors.

Non-terminating errors ^

For example, let's say I've got a script that checks to see whether a file exists or not. I'll call it ErrorExample.ps1. This script uses Test-Path to confirm whether a file exists. If it doesn't, it will return an error via the Write-Error cmdlet. This error will be non-terminating because Write-Error always returns non-terminating errors.

if (-not (Test-Path -Path C:\DoesNotExist.txt)) {
    Write-Error 'The file does not exist'
} else {
    Write-Host 'The file does exist'
}
Write-Host 'Continuing script regardless if file exists or not...'

The script will continue executing code whether or not that file exists as shown below.

Non terminating error

Non terminating error

This is a non-terminating error example because Write-Error did not terminate the script at line two. Instead, it returned the error to the console and kept going. This scenario sometimes isn't desirable. Perhaps that file you're checking for is critical to the success of the lines below it. In that case, you'd want the script to stop execution completely. You'd know that if that file doesn't exist, the rest of the script isn't going to work.

Terminating errors ^

Terminating errors are the second type of error in PowerShell. We can think of terminating errors as exceptions. Exceptions are either errors that terminate a script completely or ones PowerShell "throws" into a catch block to handle the error and perform whatever necessary actions after throwing the exception.

One way a scripter can invoke a terminating error is by using the throw keyword. This PowerShell construct creates a terminating error while also throwing an exception. Using the example above, let's say that file is critical and we'd like to stop script execution if it doesn't exist. We could replace Write-Error with throw instead.

if (-not (Test-Path -Path C:\DoesNotExist.txt)) {
    throw 'The file does not exist'
} else {
    Write-Host 'The file does exist'
}

Write-Host 'Continuing script regardless if file exists or not...'

Notice now that line seven doesn't run; throw has stopped the script at line two.

Terminating error

Terminating error

Turning non-terminating into terminating errors ^

It's sometimes hard to replace all Write-Error references and other actions that produce non-terminating errors with throw statements. Instead, you can keep all of those non-terminating error-producing commands in your scripts and "convert" them to terminating errors.

If you'd like to turn all non-terminating errors into terminating ones, you can perform a global action change by setting the $ErrorActionPreference variable to Stop. This automatic variable controls non-terminating error behavior. By setting $ErrorActionPreference to Stop, you're telling PowerShell to treat all instances where a non-terminating error occurs as terminating. This action applies across the board.

However, maybe you'd rather not change all non-terminating errors to terminating ones and pick certain ones instead. Using the common parameter ErrorAction applied to all cmdlets and advanced functions, you can make this happen.

In our example again, I can actually "override" the Write-Error cmdlet's behavior by forcing it to throw a terminating error. I'll use the ErrorAction parameter and set it to Stop.

Subscribe to 4sysops newsletter!

Write-Error 'The file does not exist' -ErrorAction Stop

When the script runs now, you'll see that it stops execution without using the throw keyword. You can use the ErrorAction parameter on every cmdlet and advanced function in PowerShell. It is a great way to choose which commands should stop script execution and which ones should not. Depending on the severity and dependencies further down in the script, this may or not may be necessary.

avataravatar