NAME
Write-Error
SYNOPSIS
Writes an object to the error stream.SYNTAX
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
] [-CategoryReason
] [-CategoryTargetName ] [-CategoryTargetType ] [-ErrorId ] -Message
[-RecommendedAction ] [-TargetObject 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
] [-CategoryReason
] [-CategoryTargetName ] [-CategoryTargetType ] [-ErrorId ] -Exception
[[-Message ] [-RecommendedAction ] [-TargetObject ] Write-Error [-CategoryActivity
] [-CategoryReason ] [-CategoryTargetName ] [-CategoryTargetType
] -ErrorRecord [-RecommendedAction ] [ ] 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).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 Enumerationhttp://go.microsoft.com/fwlink/?LinkId=143600 (http://go.microsoft.com/fwlink/?LinkId=143600) in MSDN. Required? false Position? named Default value None Accept pipeline input? False Accept wildcard characters? false-CategoryActivity
Specifies the action that caused the error. 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. 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. 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. 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. 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.
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.
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 inquotation marks. You can also pipe a message string to Write-Error .
Required? true Position? named 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. 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. Required? false Position? named Default value None Accept pipeline input? False Accept wildcard characters? falseThis cmdlet supports the common parameters: Verbose, Debug, ErrorAction, ErrorVariable, WarningAction, WarningVariable, OutBuffer, PipelineVariable, and OutVariable. For more information, see about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). INPUTS
System.StringYou can pipe a string that contains an error message to Write-Error .
OUTPUTS
Error objectWrite-Error writes only to the error stream. It does not return any objects.
NOTES
Example 1: Write an error for RegistryKey object
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: Write an error message to the console
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: Write an error to the console and specify the category
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: Write an error using an Exception object
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.
RELATED LINKS
Online Version: http://go.microsoft.com/fwlink/?LinkId=821875Write-Debug
Write-Host
Write-Output
Write-Progress
Write-Verbose
Write-Warning