Skip to content

Commit bf58d3d

Browse files
Add about_Error_Handling and fix error terminology across docs
Create a comprehensive about_Error_Handling reference topic that documents PowerShell's three error categories: non-terminating, statement-terminating, and script-terminating errors. Correct false claims in about_CommonParameters and about_Preference_Variables that state -ErrorAction and $ErrorActionPreference have "no effect on terminating errors." Update about_Try_Catch_Finally, about_Throw, about_Trap, and everything-about-exceptions to use precise terminology consistent with existing usage in about_Calculated_Properties, about_Pipeline_Chain_Operators, and about_Pwsh. Fixes #1583
1 parent 39b162f commit bf58d3d

File tree

7 files changed

+501
-50
lines changed

7 files changed

+501
-50
lines changed

reference/7.6/Microsoft.PowerShell.Core/About/about_CommonParameters.md

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -105,8 +105,9 @@ the display of debugging messages when `$DebugPreference` isn't
105105
### -ErrorAction
106106

107107
Determines how the cmdlet responds to a non-terminating error from the command.
108-
This parameter works only when the command generates a non-terminating error,
109-
such as those from the `Write-Error` cmdlet.
108+
This parameter overrides the value of the `$ErrorActionPreference` variable for
109+
non-terminating errors generated by the command, such as those from the
110+
`Write-Error` cmdlet.
110111

111112
```yaml
112113
Type: ActionPreference
@@ -124,9 +125,12 @@ variable for the current command. Because the default value of the
124125
`$ErrorActionPreference` variable is `Continue`, error messages are displayed
125126
and execution continues unless you use the `ErrorAction` parameter.
126127

127-
The `ErrorAction` parameter has no effect on terminating errors (such as
128-
missing data, parameters that aren't valid, or insufficient permissions) that
129-
prevent a command from completing successfully.
128+
The `-ErrorAction` parameter doesn't prevent statement-terminating errors
129+
(such as missing data, parameters that aren't valid, or insufficient
130+
permissions) from stopping the current statement. However, when set to `Stop`,
131+
it escalates non-terminating errors to statement-terminating errors, making
132+
them catchable by `try/catch`. For more information about error categories, see
133+
[about_Error_Handling][15].
130134

131135
- `Break` Enters the debugger when an error occurs or an exception is raised.
132136
- `Continue` displays the error message and continues executing the command.
@@ -139,7 +143,10 @@ prevent a command from completing successfully.
139143
continuing execution. This value is rarely used.
140144
- `SilentlyContinue` suppresses the error message and continues executing the
141145
command.
142-
- `Stop` displays the error message and stops executing the command.
146+
- `Stop` displays the error message and stops executing the command. The
147+
`Stop` value escalates the non-terminating error to a statement-terminating
148+
error by generating an `ActionPreferenceStopException`. The error can then
149+
be caught by a `try/catch` block or `trap` statement.
143150
- `Suspend` is only available for workflows which aren't supported in
144151
PowerShell 6 and beyond.
145152

@@ -817,6 +824,7 @@ Mode LastWriteTime Length Name
817824

818825
<!-- Using backtick on cmdlet names to avoid localization -->
819826
- [about_Preference_Variables][03]
827+
- [about_Error_Handling][15]
820828
- [`Write-Debug`][11]
821829
- [`Write-Error`][12]
822830
- [`Write-Verbose`][13]
@@ -832,4 +840,5 @@ Mode LastWriteTime Length Name
832840
[12]: xref:Microsoft.PowerShell.Utility.Write-Error
833841
[13]: xref:Microsoft.PowerShell.Utility.Write-Verbose
834842
[14]: xref:Microsoft.PowerShell.Utility.Write-Warning
843+
[15]: about_Error_Handling.md
835844

0 commit comments

Comments
 (0)