Write-Error

Writes an object to the error stream.

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 do not 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 (http://go.microsoft.com/fwlink/?LinkID=145153).

Examples

Example 1

PS C:\> 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 Windows PowerShell Registry provider.

Example 2

PS C:\> 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

PS C:\> Write-Error -Message "Error: Too many input values." -Category InvalidArgument

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

Example 4

PS C:\> $E = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="http://go.microsoft.com/fwlink/?LinkID=113425"}
PS C:\> Write-Error -Exception $E -Message "Files not found. The $Files location does not 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.

Required Parameters

-ErrorRecord

Specifies an error record object that represents the error. Use the properties of the object to describe the error.

To create an error record object, use the New-Object cmdlet or get an error record object from the array in the $Error automatic variable.

Type:ErrorRecord
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Exception

Specifies an exception object that represents the error. Use the properties of the object to describe the error.

To create an exception object, use a hash table or use the New-Object cmdlet.

Type:Exception
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Message

Specifies the message text of the error. If the text includes spaces or special characters, enclose it in quotation marks. You can also pipe a message string to Write-Error.

Type:String
Aliases:Msg
Position:1
Default value:None
Accept pipeline input:True (ByValue)
Accept wildcard characters:False

Optional Parameters

-Category

Specifies the category of the error. The default value is NotSpecified.

For information about the error categories, see ErrorCategory Enumeration in the MSDN library.

Type:ErrorCategory
Position:Named
Default value:NotSpecified
Accept pipeline input:False
Accept wildcard characters:False
-CategoryActivity

Describes the action that caused the error.

Type:String
Aliases:Activity
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-CategoryReason

Explains how or why the activity caused the error.

Type:String
Aliases:Reason
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-CategoryTargetName

Specifies the name of the object that was being processed when the error occurred.

Type:String
Aliases:TargetName
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-CategoryTargetType

Specifies the type of the object that was being processed when the error occurred.

Type:String
Aliases:TargetType
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ErrorId

Specifies an ID string to identify the error. The string should be unique to the error.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-RecommendedAction

Describes the action that the user should take to resolve or prevent the error.

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-TargetObject

Specifies the object that was being processed when the error occurred. Enter the object (such as a string), a variable that contains the object, or a command that gets the object.

Type:Object
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Inputs

System.String

You can pipe a string that contains an error message to Write-Error.

Outputs

Error object

Write-Error writes only to the error stream. It does not return any objects.