PowerShell - How to use Try Catch Finally blocks for error exception handling (Windows/SharePoint)

If you are a programmer, you certainly use exception handling logic in your code or script, which is a best practice while coding. Exceptions may break your code and its necessary to catch and handle errors for a smoother execution in case something goes wrong. Identify what is wrong and ensure it does not break the code execution.

PowerShell too provides option to use try-catch blocks similar to other programming languages like .Net, Java.
Though the below examples are related to SharePoint Online, the approach remains same for any PowerShell script. You may even use try-catch with CSOM (Client Side Object Model), PnP.

Assumption - You already know basic commands of SharePoint Online Management Shell / Window ISE PowerShell to establish a connection with Microsoft Office 365 SharePoint Online Site Collection. Ensure you "Run as Administrator".

PowerShell Example - Basic Try-Catch block

try {
	Connect-SPOService -Url "https://code2care.sharepoint.com/sites/PowerShell"
}
catch {
	"There was an error connecting to the SharePoint site"
}

PowerShell Example - Catch multiple errors

try {
	//Script
}
catch [Exception 1],[Exception 2] {
    "Friendly error message"
}
catch {
    "Generic error message"
}

Within a Catch block, the current error exception information can be accessed using $_, which is also known as $PSItem. The object is of type ErrorRecord.

PowerShell Example - Access information of current exception

try {
	//Script
}
catch {
	Write-Host "There was an error, error details below"
	Write-Host $_	//This will print the error details
}

Additional properties that can be accessed related to the exception.
ScriptStackTrace
Exception
ErrorDetails

PowerShell Example - Print exact exception message

Example - You can use $_.Exception.Message to print the exact exception message

try {
	Connect-SPOService -Url "https://code2care.sharepoint.com/sites/PowerShell"
}
catch {
	Write-host "There was an error - " $_.Exception.Message
}

This will print a message - There was an error - Could not connect to SharePoint Online.

⚡️ Terminating and Non Terminating errors

Exceptions are classified into 2 types -

1. Terminating error - halt/pause the function or operation
2. Non-Terminating error - allow to continue further execution

By default, try-catch can catch only Terminating errors. In order to catch the Non-Terminating errors, set the ErrorAction parameter of the cmdlet or set $ErrorActionPreference variable.

PowerShell Example - Use 'ErrorAction' parameter to catch non-terminating error

Add '-ErrorAction Stop' at the end of cmdlet.

try {
	Connect-SPOService -Url "https://code2care.sharepoint.com/sites/PowerShell" -ErrorAction Stop
}
catch {
	Write-host "Looks like the SharePoint site does not exist, please re-check."
}

PowerShell Example - Use '$ErrorActionPreference' variable to catch non-terminating error

Add '-ErrorAction Stop' at the end of cmdlet. Set '$ErrorActionPreference = "Stop"' to make errors as terminating, and set it back to "Continue" in Finally block.

try {
	$ErrorActionPreference = "Stop"
	Connect-SPOService -Url "https://code2care.sharepoint.com/sites/PowerShell" -ErrorAction Stop
}
catch {
	Write-host "Looks like the SharePoint site does not exist, please verify."
}
finally {
	$ErrorActionPreference = "Continue"
}

We have used 2 actions for $ErrorActionPreference variable here (Stop and Continue), but it supports below values which tells what action to take for the error.

1. Continue (default action) - Display/Print error message and continue execution of further commands.
2. Stop - Terminate action with error.
3. SilentlyContinue - Do not display error message and continue.
4. Break - Debug error/exception to troubleshoot what went wrong.
5. Inquire - Ask user whether to terminate or or continue.
6. Ignore - Suppresses error and continue. Not recommended.

PowerShell Example - Use Finally block

This block runs always, irrespective of whether there was error or not. Use this section to perform action which should execute whether there was an error or not.

try {
	Connect-SPOService -Url "https://code2care.sharepoint.com/sites/PowerShell" -ErrorAction Stop
}
catch {
	Write-host "Custom message."
}
finally {
	//Write something which you want to execute always
}