Write-Error [-Category {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}] [-CategoryActivity <String>][-CategoryReason <String>] [-CategoryTargetName <String>] [-CategoryTargetType <String>] [-ErrorId <String>]-Message* <String> [-RecommendedAction <String>] [-TargetObject <Object>] [<CommonParameters>]
Write-Error [-Category {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}] [-CategoryActivity <String>][-CategoryReason <String>] [-CategoryTargetName <String>] [-CategoryTargetType <String>] [-ErrorId <String>]-Exception* <Exception> [-Message* <String>] [-RecommendedAction <String>] [-TargetObject <Object>][<CommonParameters>]
Write-Error [-CategoryActivity <String>] [-CategoryReason <String>] [-CategoryTargetName <String>][-CategoryTargetType <String>] -ErrorRecord* <ErrorRecord> [-RecommendedAction <String>] [<CommonParameters>]
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).
-Category <ErrorCategory>
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 Enumerationhttp://go.microsoft.com/fwlink/?LinkId=143600 (http://go.microsoft.com/fwlink/?LinkId=143600) in MSDN.
-CategoryActivity <String>
Specifies the action that caused the error.
-CategoryReason <String>
Specifies how or why the activity caused the error.
-CategoryTargetName <String>
Specifies the name of the object that was being processed when the error occurred.
-CategoryTargetType <String>
Specifies the type of the object that was being processed when the error occurred.
-ErrorId <String>
Specifies an ID string to identify the error. The string should be unique to the error.
-ErrorRecord <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.
-Exception <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.
-Message <String>
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 .
-RecommendedAction <String>
Specifies the action that the user should take to resolve or prevent the error.
-TargetObject <Object>
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.
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,ErrorAction, ErrorVariable, WarningAction, WarningVariable,OutBuffer, PipelineVariable, and OutVariable.
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.
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.
PS C:\> Write-Error -Message "Error: Too many input values." -Category InvalidArgument
This command declares a non-terminating error and specifies an error category.
PS C:\> $E = [System.Exception]@{$e = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="http://go.micros
oft.com/fwlink/?LinkID=113425"}HelpLink="http://go.microsoft.com/fwlink/?LinkID=113425"}
PS C:\> Write-Error $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.
This work is licensed under a Creative Commons Attribution 4.0 International. It is attributed to Microsoft Corporation and can be found here.
PowerShell Commands