Do you want to learn how to use PowerShell cmdlets with the ErrorAction parameter? This guide teaches you all you need to know about handling errors with the ErrorAction parameter.
Overview
The ErrorAction parameter belongs to the CommonParameters. PowerShell common parameters are a group of cmdlet parameters that you can use with any cmdlet.
The PowerShell ErrorAction parameter determines how PowerShell handles non-terminating errors when you run a command.
By default, a non-terminating error is generated by the Write-Error cmdlet. Additionally, a non-terminating error adds an error to the output stream without throwing an exception.
Furthermore, when you specify this parameter, it accepts seven values. Specifically, you can define the ErrorAction as Break, Continue, Ignore or Inquire.
Additionally, you can specify SilentlyContinue, Stop, or Suspend. In the third section, I will explain these options and what they do.
It is important to mention that, like most PowerShell cmdlets and parameters, the ErrorAction parameter has an alias. The alias of ErrorAction is ea.
So, instead of running specifying the full parameter, I can specify ea.
How the PowerShell ErrorAction Parameter Works
In the last section, I mentioned that the ErrorAction parameter determines how PowerShell handles non-termination errors in a command.
A non-terminating error is an error that does not stop PowerShell from executing subsequent commands after a command throws an error message.
To show how this works, I’ll run the two PowerShell commands below without specifying the ErrorAction parameter.
Get-ChildItem d:\test; Get-ChildItem D:\Hyper-V\HDDs
As shown in the screenshot below, even though the first command threw an error, PowerShell proceeded to run the second command.
Now, I’ll specify the ErrorAction parameter in the first Get-ChildItem command. Firstly, I will specify the SilentlyContinue option of the ErrorAction parameter (more on the options later).
By specifying –ErrorAction SilentlyContinue, I have instructed PowerShell not to display the error.
Essentially, –ErrorAction SilentlyContinue instructs PowerShell to suppress the error and proceed. Now, I’ll run the command, but this time, I’ll specify –ErrorAction Stop in the first Get-ChildItem command.
Unlike the last command, this time, the error terminates (stops) PowerShell from executing further commands.
So, by specifying –ErrorAction Stop in the first Get-ChildItem command, I turned the non-terminating error into a terminating error. Such is the power of the PowerShell ErrorAction parameter!
Features Of The PowerShell ErrorAction Parameter
The PowerShell ErrorAction parameter has some important features worth mentioning. Understanding these features will help you use the ErrorAction parameter effectively.
In the following subsections, I have highlighted and discussed the most important features of the ErrorAction parameter.
The ErrorAction Parameter Accepts Seven (7) Options
In the overview section of this article, I hinted that the ErrorAction parameter accepts 7 options. Additionally, in the last section, I used the SilentlyContinue and the Stop options.
I have explained these two options and the other 5 below:
- -ErrorAction SilentlyContinue. Specifying this option conceals the error message and resumes executing the command.
Even though the SilentlyContinue option suppresses the error message, it adds the error message to the$Errorautomatic variable. This is important if you need to capture the error in a catch block. - -ErrorAction Ignore. The Ignore option is similar to the SilentlyContinue option in that it also suppresses the error message.
However, unlike the SilentlyContinue option, the Ignore option does not add the error message to the$Errorautomatic variable. The implication is that if you specify the Ignore option, you effectively lose the errors and cannot capture them in acatchblock. - -ErrorAction Stop. Specifying the Stop option displays the error message on the PowerShell console and stops executing the command or any other command in the script.
Like the Ignore option, if you specify the Stop option, you’ll not be able to capture error messages in a catch block. However, the difference between Ignore and Stop is that Stop displays the error message and terminates the command.
On the other hand, Ignore does not display the error message, but it continues running the command. - -ErrorAction Break. When you specify the Break option, when an exception is raised, PowerShell enters the debugger mode.
The Break option is not available in PowerShell version 5 and lower. - -ErrorAction Continue. This is the default PowerShell ErrorAction option.
The Continue option displays the error message and continues executing the command. - -ErrorAction Inquire. This option displays the error message and also prompts you for confirmation before continuing execution.
The confirmation options Yes, Yes to All, Halt Command, or Suspend. The default is Yes. - -ErrorAction Suspend. You can only use this option in a PowerShell workflow. However, this option is not supported in PowerShell version 6 and beyond.
ErrorAction Overrides the $ErrorActionPreference Variable
When you write a script or run commands on the PowerShell console, you can specify your preferred ErrorAction before you start running any command.
To specify your preferred erroraction, use the $ErrorActionPreference variable. As you may have guessed, the $ErrorActionPreference variable supports the same options discussed in the last subsection.
So, you can specify your preferred PowerShell erroraction as Continue, SilentlyContinue, Stop, Inquire, Ignore, Suspend, or Break. Here is an example that sets the erroraction preference to SilentlyContinue.
$ErrorActionPreference = 'SilentlyContinue'
Once you specify the $ErrorActionPreference variable, any command you run after that sets the -ErrorAction parameter to SilentlyContinue. However, if you set -ErrorAction parameter in a command, the -ErrorAction you set in a command supersedes the value in the $ErrorActionPreference variable.
The -ErrorAction Stop Option Turns Non-terminating to Terminating Errors
As I have mentioned several times in this guide, when you specify the -ErrorAction parameter or the $ErrorActionPreference variable, you can set one of the 7 options.
I also mentioned earlier that when you set the -ErrorAction parameter to Stop, PowerShell displays the error message on the console and terminates the command.
Essentially, by terminating the command, -ErrorAction Stop changes the non-terminating error to a terminating error.
Use Try/Catch Block to Manage Errors in PowerShell
You cannot discuss error handling in PowerShell without mentioning the Try/Catch/Finally block. The Try/Catch/Finally block has three blocks.
Essentially, you execute the command in the try block. Then, manage the error by specifying the -ErrorAction parameter in the command.
However, to capture the error message, you use the catch block. Here is an example…
$error.Clear()
Try {
Get-ChildItem d:\test -ErrorAction SilentlyContinue
}
catch {
}
Finally {
Write-Host $error.Exception.Message
}
The Catch Block Holds the $PSItem Automatic Variable
Within the catch block, there is an important automatic variable, $PSItem. This is a ErrorRecord type that holds the details about the exception.
The $PSItem automatic variable has some important properties worth noting. I have explained some of the properties of the $PSItem automatic variable below:
- $PSItem.ToString(). The ToString() method of the $PSItem variable displays the clean error message caught in the
catchblock. - $PSItem.InvocationInfo. This stores some information about the cmdlet that threw the error captured in the
catchblock. - $PSItem.ScriptStackTrace. The ScriptStackTrace property of the $PSItem variable shows the order of function calls that got you to the code where the exception was generated.
- $PSItem.Exception. This displays the actual exception thrown by the command.
- $PSItem.Exception.Message. The Message property is a sub-property of the Exception property.
The $PSItem.Exception.Message property displays the message that shows the reason for the exception. - $PSItem.Exception.InnerException. Error messages generated by the PowerShell ErrorAction parameter can contain inner exceptions.
This happens when the code you’re calling catches an exception but throws a different exception. If you want to see the other error messages not captured by $PSItem.Exception.Message, use $PSItem.Exception.InnerException.
PowerShell ErrorAction Parameter Examples
Finally, you’ve read this article to the fun part. In this section, I have discussed different examples and applications of the PowerShell ErrorAction parameter.
1. PowerShell ErrorAction SilentlyContinue Option in a Try/Catch/Finally Block To Display Errors
When you specify the SilentlyContinue option in the -ErrorAction parameter, PowerShell suppresses all error messages and continues running the command.
However, to capture and display the error, you have to introduce the try/catch/finally block. The code below displays the error message captured in the Catch block.
$error.Clear()
try {
Get-Content D:\PS-Tutorial\folder-names.txt -ErrorAction SilentlyContinue
Get-EventLog -LogName Systerr
}
Catch {
}
Finally {
Write-Host $error.Exception.Message
}
2. Use PowerShell ErrorAction Parameter in an Get-ADUser Command
Ideally, when you run a command and specify –ErrorAction SilentlyContinue, PowerShell suppresses all errors and continues running the command. Unfortunately, when you do this with the Get-ADUser command, it does not work as expected.
Here is an example.
Get-ADUser -Identity Abj -ErrorAction SilentlyContinue
The command displays an error message instead of suppressing it.
To fix this problem and run the Get-AdUser command without displaying an error message, run the command in a try/catch block.
try {Get-ADUser -Identity Abj -ErrorAction SilentlyContinue} catch {}
Now, the command suppresses the error message.
However, if you want to display a “clean” version of the error message, introduce a finally block into the try/catch block…
$error.Clear(); try {Get-ADUser -Identity Abj -ErrorAction SilentlyContinue} catch {} Finally { Write-Host $error.Exception.Message}
The command displays a “clean” version of the error message. You can save this error in an error log text file. Then, review it to see errors and failures.
This is particularly useful if you’re running the Get-ADUser command on multiple user accounts.
3. Suppress Error in PowerShell and Display a Custom Error Message with the PowerShell ErrorAction Parameter
One common way to suppress error messages in PowerShell is to run a command with -ErrorAction SilentlyContinue. When you do this, you can display the error message in the final block of a try/catch/final block.
Alternatively, you can display a custom error message
I have shown multiple examples that demonstrate how to display the error message captured in the $error automatic variable.
Similar to the examples I already shared, you can display a custom error message in the final block of a try/catch/final block. Here is the command I used to show how to display the error in the $error automatic variable.
$error.Clear(); try {Get-ADUser -Identity Abj -ErrorAction SilentlyContinue} catch {} Finally { Write-Host $error.Exception.Message}
Similarly, you can replace the message in the final block with a custom message, as shown below.
$error.Clear(); try {Get-ADUser -Identity Abj -ErrorAction SilentlyContinue} catch {} Finally { Write-Host "the command could not be completed because an error has occured"}
I have highlighted the custom error message in the screenshot below.
Frequently Asked Questions
The ErrorAction parameter is a common parameter you can use to determine how PowerShell handles non-terminating errors.
This is called a common parameter because it is common to all PowerShell cmdlets.
When you run a PowerShell command and specify the ErrorAction parameter with the SilentlyContinue option, PowerShell suppresses all errors and continues running the command.
To add a try/catch block to a PowerShell script, enter a command in the try block, then capture the error in the catch block.
Here is an example of a try/catch block:
try {Get-ADUser -Identity Abj -ErrorAction SilentlyContinue} catch {}
To read more about the try/catch/finally block, read my article – PowerShell Try Catch Finally And Error Handling.
To stop error messages from displaying in PowerShell, specify the ErrorAction parameter with the SilentlyContinue option. Additionally, run the command within the try block of a try/catch block.
To clear the $error automatic variable in PowerShell, use the command below:
$error.Clear()
It is common practice to have this as your first command in the finally block of a try/catch/finally block. This is to ensure that PowerShell clears all previous errors it saved in the $error variable.
So, when you display the errors in the $error variable, they will be errors for the current command.
The trap keyword defines a list of statements that PowerShell runs when a terminating error occurs.
Conclusion
If you really want to develop PowerShell scripts like a pro, you must understand how to handle errors. The PowerShell ErrorAction parameter is one powerful error management tool every serious PowerShell student must know how to use.
With this in mind, I hope I have simplified this all-important PowerShell topic for you. If I did, click on “Yes” beside the “Was this page helpful” question below.
You may also express your thoughts and opinions by using the “Leave a Comment” form at the bottom of this page.
Before you go, why not enhance your PowerShell skills by reading more of our Windows PowerShell How-To Guides or Windows PowerShell Explained guides?
