Export (0) Print
Expand All

Write-Error

Published: February 29, 2012

Updated: August 15, 2012

Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0

Write-Error

Writes an object to the error stream.

Syntax

Parameter Set: NoException
Write-Error [-Message] <String> [-Category <ErrorCategory> ] [-CategoryActivity <String> ] [-CategoryReason <String> ] [-CategoryTargetName <String> ] [-CategoryTargetType <String> ] [-ErrorId <String> ] [-RecommendedAction <String> ] [-TargetObject <Object> ] [ <CommonParameters>]

Parameter Set: ErrorRecord
Write-Error -ErrorRecord <ErrorRecord> [-CategoryActivity <String> ] [-CategoryReason <String> ] [-CategoryTargetName <String> ] [-CategoryTargetType <String> ] [-RecommendedAction <String> ] [ <CommonParameters>]

Parameter Set: WithException
Write-Error -Exception <Exception> [-Category <ErrorCategory> ] [-CategoryActivity <String> ] [-CategoryReason <String> ] [-CategoryTargetName <String> ] [-CategoryTargetType <String> ] [-ErrorId <String> ] [-Message <String> ] [-RecommendedAction <String> ] [-TargetObject <Object> ] [ <CommonParameters>]




Detailed 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<ErrorCategory>

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

For information about the error categories, see "ErrorCategory Enumeration" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkId=143600.


Aliases

none

Required?

false

Position?

named

Default Value

NotSpecified

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-CategoryActivity<String>

Describes the action that caused the error.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-CategoryReason<String>

Explains how or why the activity caused the error.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-CategoryTargetName<String>

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


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-CategoryTargetType<String>

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


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-ErrorId<String>

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


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

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


Aliases

none

Required?

true

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

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


Aliases

none

Required?

true

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

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


Aliases

none

Required?

true

Position?

1

Default Value

None

Accept Pipeline Input?

true (ByValue)

Accept Wildcard Characters?

false

-RecommendedAction<String>

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


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

-TargetObject<Object>

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.


Aliases

none

Required?

false

Position?

named

Default Value

None

Accept Pipeline Input?

false

Accept Wildcard Characters?

false

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see  about_CommonParameters (http://go.microsoft.com/fwlink/p/?LinkID=113216).

Inputs

The input type is the type of the objects that you can pipe to the cmdlet.

  • System.String

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


Outputs

The output type is the type of the objects that the cmdlet emits.

  • Error object

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


Examples

-------------------------- EXAMPLE 1 --------------------------

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:\> Get-ChildItem | ForEach-Object { if ($_.GetType().ToString() -eq "Microsoft.Win32.RegistryKey") {Write-Error "Invalid object" -ErrorID B1 -Targetobject $_ } else {$_ } }

-------------------------- EXAMPLE 2 --------------------------

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 "Access denied."

-------------------------- EXAMPLE 3 --------------------------

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


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

-------------------------- EXAMPLE 4 --------------------------

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.


PS C:\> $e = [System.Exception]@{$e = [System.Exception]@{Source="Get-ParameterNames.ps1";HelpLink="http://go.microsoft.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."

Related topics



Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft