Skip to content

Commit bd9a431

Browse files
SufficientDaikonclaude
authored andcommitted
Extend error handling accuracy to about_Throw, about_Try_Catch_Finally
- about_Throw: Add $ErrorActionPreference suppression caveat (throw CAN be suppressed by SilentlyContinue/Ignore), add NOTE block with Ignore still recording in $Error, update description to "by default" - about_Try_Catch_Finally: Add NOTE about throw suppression with cross-ref to about_Error_Handling, fix $tempPath -> $tempFile code bug (line 264) - about_Preference_Variables: Fix Ignore bullet - clarify that Ignore only prevents $Error recording for non-terminating errors, not terminating - everything-about-exceptions: Change -ErrorAction Stop from "script-terminating" to "terminating" (context-dependent behavior) All claims verified against live PowerShell 7.6 behavior. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent d91c08d commit bd9a431

File tree

4 files changed

+35
-14
lines changed

4 files changed

+35
-14
lines changed

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -391,7 +391,9 @@ The valid values are as follows:
391391
command. Unlike **SilentlyContinue**, **Ignore** doesn't add the error
392392
message to the `$Error` automatic variable. The **Ignore** value is also
393393
valid for `$ErrorActionPreference`, where it suppresses both non-terminating
394-
and statement-terminating errors without recording them in `$Error`.
394+
and statement-terminating errors. However, **Ignore** only prevents `$Error`
395+
recording for non-terminating errors. Terminating errors that are suppressed
396+
by `Ignore` are still recorded in `$Error`.
395397
- **Inquire**: Displays the error message and asks you whether you want to
396398
continue.
397399
- **SilentlyContinue**: No effect. The error message isn't displayed and

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

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
description: Describes the `throw` keyword, which generates a script-terminating error.
2+
description: Describes the `throw` keyword, which generates a script-terminating error by default.
33
Locale: en-US
4-
ms.date: 01/18/2026
4+
ms.date: 03/29/2026
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_throw?view=powershell-7.6&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about_Throw
@@ -10,18 +10,31 @@ title: about_Throw
1010

1111
## Short description
1212

13-
Describes the `throw` keyword that generates a script-terminating error.
13+
Describes the `throw` keyword that generates a script-terminating error by
14+
default.
1415

1516
## Long description
1617

17-
The `throw` keyword causes a script-terminating error. You can use the `throw`
18-
keyword to stop the processing of a command, function, or script.
18+
The `throw` keyword causes a script-terminating error by default. You can use
19+
the `throw` keyword to stop the processing of a command, function, or script.
1920

2021
Unlike statement-terminating errors (generated by
2122
`$PSCmdlet.ThrowTerminatingError()`), the `throw` keyword unwinds the entire
2223
call stack. Execution stops completely unless the error is caught by a
23-
`try/catch` block or `trap` statement. For more information about error
24-
categories, see [about_Error_Handling](about_Error_Handling.md).
24+
`try/catch` block or `trap` statement.
25+
26+
> [!NOTE]
27+
> `$ErrorActionPreference` can suppress `throw`. When set to
28+
> `SilentlyContinue` or `Ignore`, the error does not propagate and
29+
> execution continues at the next statement. When calling an advanced
30+
> function with `-ErrorAction SilentlyContinue`, the parameter translates
31+
> to a scope-local `$ErrorActionPreference` value, so it also suppresses
32+
> `throw` inside that function. Even when suppressed, `throw` still records
33+
> an entry in `$Error``Ignore` only prevents `$Error` recording for
34+
> non-terminating errors.
35+
36+
For more information about error categories and `$ErrorActionPreference`
37+
behavior, see [about_Error_Handling](about_Error_Handling.md).
2538

2639
For example, you can use the `throw` keyword in the statement block of an `if`
2740
statement to respond to a condition or in the `catch` block of a

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

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes how to use the `try`, `catch`, and `finally` blocks to handle statement-terminating and script-terminating errors.
33
Locale: en-US
4-
ms.date: 01/13/2026
4+
ms.date: 03/29/2026
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_try_catch_finally?view=powershell-7.6&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about_Try_Catch_Finally
@@ -27,8 +27,13 @@ A statement-terminating error stops the current statement from running, but
2727
PowerShell continues at the next statement unless the error is also
2828
script-terminating. A script-terminating error (such as an error produced by
2929
the `throw` keyword) stops the entire script unless caught by a `try/catch`
30-
block or `trap` statement. In other languages, such as C\#, terminating errors
31-
are referred to as exceptions.
30+
block or `trap` statement.
31+
32+
> [!NOTE]
33+
> `$ErrorActionPreference` can suppress `throw`. When set to
34+
> `SilentlyContinue` or `Ignore`, the error does not propagate and
35+
> execution continues at the next statement. For details, see the
36+
> [_throw_ suppression section][07] in **about_Error_Handling**.
3237
3338
Use the `try` block to define a section of a script in which you want
3439
PowerShell to monitor for errors. When an error occurs within the `try` block,
@@ -261,7 +266,7 @@ try {
261266
"An error occurred that could not be resolved."
262267
} finally {
263268
$wc.Dispose()
264-
if (Test-Path $tempPath) { Remove-Item $tempFile }
269+
if (Test-Path $tempFile) { Remove-Item $tempFile }
265270
}
266271
```
267272

@@ -281,3 +286,4 @@ try {
281286
[04]: about_Throw.md
282287
[05]: about_Trap.md
283288
[06]: about_Error_Handling.md
289+
[07]: about_Error_Handling.md#script-terminating-errors

reference/docs-conceptual/learn/deep-dives/everything-about-exceptions.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ At line:1 char:1
9292
#### Write-Error -ErrorAction Stop
9393

9494
I mentioned that `Write-Error` doesn't throw a terminating error by default. If you specify
95-
`-ErrorAction Stop`, `Write-Error` generates a script-terminating error that can be handled with a
95+
`-ErrorAction Stop`, `Write-Error` generates a terminating error that can be handled with a
9696
`catch`.
9797

9898
```powershell
@@ -104,7 +104,7 @@ Thank you to Lee Dailey for reminding about using `-ErrorAction Stop` this way.
104104
#### Cmdlet -ErrorAction Stop
105105

106106
If you specify `-ErrorAction Stop` on any advanced function or cmdlet, it turns all `Write-Error`
107-
statements into script-terminating errors that stop execution or that can be handled by a `catch`.
107+
statements into terminating errors that stop execution or that can be handled by a `catch`.
108108

109109
```powershell
110110
Start-Something -ErrorAction Stop

0 commit comments

Comments
 (0)