Write-Error

Syntax

Write-Error
     [-Message] <string>
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]

Write-Error
     [-Exception] <Exception>
     [-Message <string>]
     [-Category <ErrorCategory>]
     [-ErrorId <string>]
     [-TargetObject <Object>]
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]

Write-Error
     [-ErrorRecord] <ErrorRecord>
     [-RecommendedAction <string>]
     [-CategoryActivity <string>]
     [-CategoryReason <string>]
     [-CategoryTargetName <string>]
     [-CategoryTargetType <string>]
     [<CommonParameters>]

Description

The Write-Error cmdlet declares a non-terminating error. By default, errors are sent in the error stream to the host program to be displayed, along with output.

To write a non-terminating error, enter an error message string, an ErrorRecord object, or an Exception object. Use the other parameters of Write-Error to populate the error record.

Non-terminating errors write an error to the error stream, but they don't stop command processing. If a non-terminating error is declared on one item in a collection of input items, the command continues to process the other items in the collection.

To declare a terminating error, use the Throw keyword. For more information, see about_Throw.

Examples

Example 1: Write an error for RegistryKey object

Get-ChildItem | ForEach-Object {
    if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey")
    {
        Write-Error "Invalid object" -ErrorId B1 -TargetObject $_
    }
    else
    {
        $_
    }
}

This command declares a non-terminating error when the Get-ChildItem cmdlet returns a Microsoft.Win32.RegistryKey object, such as the objects in the HKLM: or HKCU: drives of the PowerShell Registry provider.

Example 2: Write an error message to the console

Write-Error "Access denied."

This command declares a non-terminating error and writes an "Access denied" error. The command uses the Message parameter to specify the message, but omits the optional Message parameter name.

Example 3: Write an error to the console and specify the category

Write-Error -Message "Error: Too many input values." -Category InvalidArgument

This command declares a non-terminating error and specifies an error category.

Example 4: Write an error using an Exception object

$E = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="https://go.microsoft.com/fwlink/?LinkID=113425"}
Write-Error -Exception $E -Message "Files not found. The $Files location doesn't contain any XML files."

This command uses an Exception object to declare a non-terminating error.

The first command uses a hash table to create the System.Exception object. It saves the exception object in the $E variable. You can use a hash table to create any object of a type that has a null constructor.

The second command uses the Write-Error cmdlet to declare a non-terminating error. The value of the Exception parameter is the Exception object in the $E variable.

Parameters

-Category

-CategoryActivity

-CategoryReason

-CategoryTargetName

-CategoryTargetType

-ErrorId

-ErrorRecord

-Exception

-Message

-RecommendedAction

-TargetObject

Inputs

String

You can pipe a string that contains an error message to this cmdlet.

Outputs

None

This cmdlet returns no output. It only writes to the error message stream.

Notes

Write-Error doesn't change the value of the $? automatic variable, therefore it doesn't signal a terminating error condition. To signal a terminating error, use the $PSCmdlet.WriteError() method.

Related Links

• about_Automatic_Variables
• about_Output_Streams
• about_Redirection
• Write-Debug
• Write-Host
• Write-Output
• Write-Progress
• Write-Verbose
• Write-Warning