Write-Error

Writes an object to the error stream.
Write-Error [-Message*] <String> [-Category { |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  ||  |  |  |  |  |  |  | }] [-CategoryActivity [<String>]] [-CategoryReason [<String>]] [-CategoryTargetName[<String>]] [-CategoryTargetType [<String>]] [-ErrorId [<String>]] [-RecommendedAction [<String>]] [-TargetObject[<Object>]] [<CommonParameters>]
Write-Error [-Category { |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  || }] [-CategoryActivity [<String>]] [-CategoryReason [<String>]] [-CategoryTargetName [<String>]][-CategoryTargetType [<String>]] [-ErrorId [<String>]] [-Message* <String>] [-RecommendedAction [<String>]][-TargetObject [<Object>]] -Exception* <Exception> [<CommonParameters>]
Write-Error [-CategoryActivity [<String>]] [-CategoryReason [<String>]] [-CategoryTargetName [<String>]][-CategoryTargetType [<String>]] [-RecommendedAction [<String>]] -ErrorRecord* <ErrorRecord> [<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).

Parameters
-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 Enumeration (http://go.microsoft.com/fwlink/?LinkId=143600) in MSDN.
-CategoryActivity [<String>]

  • Default value is None

Specifies the action that caused the error.
-CategoryReason [<String>]

  • Default value is None

Specifies how or why the activity caused the error.
-CategoryTargetName [<String>]

  • Default value is None

Specifies the name of the object that was being processed when the error occurred.
-CategoryTargetType [<String>]

  • Default value is None

Specifies the type of the object that was being processed when the error occurred.
-ErrorId [<String>]

  • Default value is None

Specifies an ID string to identify the error. The string should be unique to the error.
-ErrorRecord <ErrorRecord>

  • This value is required
  • Default value is None

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>

  • This value is required
  • Default value is None

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>

  • This value is required
  • Default value is None
  • Accepts pipeline input ByValue

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>]

  • Default value is None

Specifies the action that the user should take to resolve or prevent the error.
-TargetObject [<Object>]

  • Default value is None

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.
<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,ErrorAction, ErrorVariable, WarningAction, WarningVariable,OutBuffer, PipelineVariable, and OutVariable.

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.

Examples
  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.

  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.

  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.

  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

Write-Debug
Write-Host
Write-Output
Write-Progress
Write-Verbose
Write-Warning

Back to PowerShell Command list