Write-Error
SYNOPSIS
Writes an object to the error stream.
SYNTAX
NoException (Default)
Write-Error [-Message] <String> [-Category <ErrorCategory>] [-ErrorId <String>] [-TargetObject <Object>]
[-RecommendedAction <String>] [-CategoryActivity <String>] [-CategoryReason <String>]
[-CategoryTargetName <String>] [-CategoryTargetType <String>] [<CommonParameters>]
WithException
Write-Error -Exception <Exception> [[-Message] <String>] [-Category <ErrorCategory>] [-ErrorId <String>]
[-TargetObject <Object>] [-RecommendedAction <String>] [-CategoryActivity <String>] [-CategoryReason <String>]
[-CategoryTargetName <String>] [-CategoryTargetType <String>] [<CommonParameters>]
ErrorRecord
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 (../Microsoft.PowerShell.Core/About/about_Throw.md).
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 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.
PARAMETERS
-Category
Specifies the category of the error. The default value is NotSpecified . The acceptable values for this parameter are:
- NotSpecified
- OpenError
- CloseError
- DeviceError
- DeadlockDetected
- InvalidArgument
- InvalidData
- InvalidOperation
- InvalidResult
- InvalidType
- MetadataError
- NotImplemented
- NotInstalled
- ObjectNotFound
- OperationStopped
- OperationTimeout
- SyntaxError
- ParserError
- PermissionDenied
- ResourceBusy
- ResourceExists
- ResourceUnavailable
- ReadError
- WriteError
- FromStdErr
- SecurityError
- ProtocolError
- ConnectionError
- AuthenticationError
- LimitsExceeded
- QuotaExceeded
- NotEnabled
For information about the error categories, see ErrorCategory Enumeration (https://go.microsoft.com/fwlink/?LinkId=143600).
Type: System.Management.Automation.ErrorCategory
Parameter Sets: NoException, WithException
Aliases:
Accepted values: NotSpecified, OpenError, CloseError, DeviceError, DeadlockDetected, InvalidArgument, InvalidData, InvalidOperation, InvalidResult, InvalidType, MetadataError, NotImplemented, NotInstalled, ObjectNotFound, OperationStopped, OperationTimeout, SyntaxError, ParserError, PermissionDenied, ResourceBusy, ResourceExists, ResourceUnavailable, ReadError, WriteError, FromStdErr, SecurityError, ProtocolError, ConnectionError, AuthenticationError, LimitsExceeded, QuotaExceeded, NotEnabled
Required: False
Position: Named
Default value: NotSpecified
Accept pipeline input: False
Accept wildcard characters: False
-CategoryActivity
Specifies the action that caused the error.
Type: System.String
Parameter Sets: (All)
Aliases: Activity
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-CategoryReason
Specifies how or why the activity caused the error.
Type: System.String
Parameter Sets: (All)
Aliases: Reason
Required: False
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: System.String
Parameter Sets: (All)
Aliases: TargetName
Required: False
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: System.String
Parameter Sets: (All)
Aliases: TargetType
Required: False
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: System.String
Parameter Sets: NoException, WithException
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-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: System.Management.Automation.ErrorRecord
Parameter Sets: ErrorRecord
Aliases:
Required: True
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: System.Exception
Parameter Sets: WithException
Aliases:
Required: True
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: System.String
Parameter Sets: NoException
Aliases: Msg
Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
Type: System.String
Parameter Sets: WithException
Aliases: Msg
Required: False
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
-RecommendedAction
Specifies the action that the user should take to resolve or prevent the error.
Type: System.String
Parameter Sets: (All)
Aliases:
Required: False
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, a variable that contains the object, or a command that gets the object.
Type: System.Object
Parameter Sets: NoException, WithException
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
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.
NOTES
`Write-Error` does not change the value of the `$?` automatic variable, therefore it does not signal a terminating error condition. To signal a terminating error, use the $PSCmdlet.WriteError() (/dotnet/api/system.management.automation.cmdlet.writeerror)method.