PowerShell ErrorRecord

An error in PowerShell is an object, not a string. Knowing its shape turns error handling from guesswork into inspection.

Lesson 2 min read Windows PowerShell 5.1 and PowerShell 7

Documentation: Microsoft Learn

Written and tested by Dhrub Bharali · Updated 02 October 2026

Overview

The useful properties are $_.Exception.Message for the human-readable text, $_.CategoryInfo for the classification, $_.FullyQualifiedErrorId for a stable identifier you can branch on, $_.TargetObject for the thing that failed, and $_.ScriptStackTrace for where it happened.

FullyQualifiedErrorId is the one worth remembering. It does not change with locale or wording, so comparing against it keeps working when message text does not. Message strings get reworded between versions and are translated on non-English systems.

$Error is an automatic array of recent errors, newest first, so $Error[0] is the most recent one. It is the fastest way to inspect a failure you did not plan for: run the command, then poke at $Error[0] until you understand it.

Inspect this example’s structure

Read the command and its supplied arguments. This example requires real PowerShell or its module; this diagram does not execute it.

try {
  Get-Item 'C:\NoSuchFile.txt' -ErrorAction Stop }
catch {
  [pscustomobject]@{
    Message = $_.Exception.Message
    Category = $_.CategoryInfo.Category
    ErrorId = $_.FullyQualifiedErrorId
  } }

Stage 1tryPositional values or no named parameters

What happens

-ErrorAction Stop makes the missing-file error terminating so catch receives it. The catch block builds an object from three properties of the ErrorRecord rather than printing a string, so you can see the classification and the error id next to the message. That error id is what you would use in an if statement to handle this specific failure.

Worth remembering

Errors are ErrorRecord objects with inspectable properties.
Branch on $_.FullyQualifiedErrorId, not on message text.
$Error[0] is the most recent error in the session.
$_.ScriptStackTrace tells you where it came from.

Primary documentation

Get-Item reference

Try it

Illustrative output · values vary by environment

1PS> try {

2PS> Get-Item 'C:\NoSuchFile.txt' -ErrorAction Stop }

3PS> catch {

4PS> [pscustomobject]@{

5PS> Message = $_.Exception.Message

6PS> Category = $_.CategoryInfo.Category

7PS> ErrorId = $_.FullyQualifiedErrorId

8PS> } }

Example reader

Inspect this page's example

Fictional browser data when supported

Run supported commands against the practice data, or inspect the example without executing it.

try {
  Get-Item 'C:\NoSuchFile.txt' -ErrorAction Stop }
catch {
  [pscustomobject]@{
    Message = $_.Exception.Message
    Category = $_.CategoryInfo.Category
    ErrorId = $_.FullyQualifiedErrorId
  } }

Ready to inspect.

Inspects three properties of the ErrorRecord instead of printing a string.

Show reference output

Illustrative output · values vary by environment

Message               Category          ErrorId
-------               --------          -------
Sample error message  InvalidOperation  SampleErrorId

Practise this

Handle an explicit failure

Throw the message Validation failed inside try. Catch it and return Input rejected.

Review the lesson

Keep going

Next: PowerShell Verbose and diagnostic streams

Check your understanding