Comprehensive accuracy overhaul: escalation semantics, asymmetry, parse errors

Major corrections verified against PowerShell engine source code:

- Fix: -ErrorAction Stop produces script-terminating errors, not
  statement-terminating. ActionPreferenceStopException sets
  SuppressPromptInInterpreter=true, causing call-stack unwinding.
  Fixed across all 4 affected files.

- Add: New "$ErrorActionPreference asymmetry" section in
  about_Error_Handling documenting that $ErrorActionPreference applies
  to BOTH non-terminating and statement-terminating errors, while
  -ErrorAction only affects non-terminating errors. Includes runnable
  demo and IMPORTANT callout for exceptions (SuppressPromptInInterpreter,
  PS classes, PipelineStoppedException).

- Add: Parse errors to script-terminating generators list (per
  mklement0 review comment).

- Fix: about_Preference_Variables Ignore bullet incorrectly stated
  "Ignore isn't a valid value for $ErrorActionPreference" — it is
  accepted (only Suspend is rejected per ExecutionContext.cs).

- Fix: NOTE block on ThrowTerminatingError now correctly explains
  that $ErrorActionPreference can suppress it via the engine's
  statement-level handler in MiscOps.CheckActionPreference.

- Fix: Summary table updated — -ErrorAction Stop moved from
  statement-terminating to script-terminating column, new row added
  for $ErrorActionPreference behavior per error type.

- Fix: everything-about-exceptions.md — three remaining instances of
  vague "terminating error" updated to "script-terminating error" for
  throw and -ErrorAction Stop contexts.

All claims verified with live PowerShell 7.x tests:
  1. -ErrorAction Stop: next statement in scriptblock does NOT run (script-terminating)
  2. Parse errors: caught as MethodInvocationException
  3. $ErrorActionPreference='Ignore': accepted without error
  4. $ErrorActionPreference='SilentlyContinue': suppresses ThrowTerminatingError
  5. -ErrorAction SilentlyContinue: does NOT suppress ThrowTerminatingError

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

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

@@ -144,7 +144,7 @@ catchable by `try/catch`. For more information about error categories, see
 - `SilentlyContinue` suppresses the error message and continues executing the
   command.
 - `Stop` displays the error message and stops executing the command. The
-  `Stop` value escalates the non-terminating error to a statement-terminating
+  `Stop` value escalates the non-terminating error to a script-terminating
   error by generating an `ActionPreferenceStopException`. The error can then
   be caught by a `try/catch` block or `trap` statement.
 - `Suspend` is only available for workflows which aren't supported in

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

@@ -60,8 +60,6 @@ Statement-terminating errors are generated by:
   compiled cmdlets
 - Engine errors such as `CommandNotFoundException` (calling a command that does
   not exist) and `ParameterBindingException` (invalid parameter arguments)
-- Non-terminating errors **escalated** by `-ErrorAction Stop` or
-  `$ErrorActionPreference = 'Stop'` (see [How escalation works][05])
 - .NET method calls that throw exceptions, such as `[int]::Parse('abc')`
 
 ```powershell
@@ -73,10 +71,14 @@ Write-Output 'This still runs'
 Statement-terminating errors can be caught by `try/catch` and `trap`.
 
 > [!NOTE]
-> `.ThrowTerminatingError()` does not consult `-ErrorAction` or
-> `$ErrorActionPreference` (except for the `Break` value, which enters the
-> debugger). Once a cmdlet calls `.ThrowTerminatingError()`, the error is
-> always thrown regardless of the caller's preferences.
+> `.ThrowTerminatingError()` does not consult the `-ErrorAction` parameter
+> (except for the `Break` value, which enters the debugger). However,
+> `$ErrorActionPreference` _does_ apply to statement-terminating errors
+> through the engine's statement-level handler. For example,
+> `$ErrorActionPreference = 'SilentlyContinue'` can suppress a
+> statement-terminating error so that the script continues at the next
+> statement. The `-ErrorAction` parameter cannot do this. For details, see
+> [The $ErrorActionPreference asymmetry][09].
 
 ### Script-terminating errors
 
@@ -85,6 +87,9 @@ completely unless the error is caught by a `try/catch` block or `trap`
 statement. Script-terminating errors are generated by:
 
 - The `throw` keyword
+- Parse errors (syntax errors that prevent the script from being compiled)
+- Non-terminating errors **escalated** by `-ErrorAction Stop` or
+  `$ErrorActionPreference = 'Stop'` (see [How escalation works][05])
 - Certain critical engine failures
 
 ```powershell
@@ -204,14 +209,15 @@ When `-ErrorAction` is specified on a command, it takes precedence over
 ### How escalation works
 
 When `-ErrorAction Stop` or `$ErrorActionPreference = 'Stop'` is in effect,
-PowerShell converts non-terminating errors into statement-terminating errors
+PowerShell converts non-terminating errors into script-terminating errors
 using the following mechanism:
 
 1. A cmdlet calls `WriteError()` internally to emit a non-terminating error.
 1. The engine checks the effective `ErrorAction` preference for the command.
 1. Because the preference is `Stop`, the engine creates an
    `ActionPreferenceStopException` that wraps the original error record.
-1. This exception propagates as a statement-terminating error.
+1. This exception has `SuppressPromptInInterpreter` set to `true`, which
+   causes it to propagate up the call stack like a script-terminating error.
 1. If caught by `catch`, the original error information is accessible through
    `$_.Exception.ErrorRecord`.
 
@@ -225,7 +231,7 @@ try {
 }
 
 try {
-    # With -ErrorAction Stop: escalated to statement-terminating
+    # With -ErrorAction Stop: escalated to script-terminating
     Write-Error 'This becomes terminating' -ErrorAction Stop
 } catch {
     Write-Output "Caught: $_"   # Reached
@@ -243,6 +249,51 @@ try {
 }
 ```
 
+### The $ErrorActionPreference asymmetry
+
+The `-ErrorAction` parameter and the `$ErrorActionPreference` variable behave
+differently with terminating errors. This is an important asymmetry:
+
+- **`-ErrorAction`** only affects **non-terminating** errors. When a cmdlet
+  calls `$PSCmdlet.ThrowTerminatingError()`, the `-ErrorAction` parameter is
+  ignored (except for `Break`, which enters the debugger). The error is always
+  thrown.
+
+- **`$ErrorActionPreference`** affects **both** non-terminating and
+  statement-terminating errors. The engine's statement-level error handler
+  reads `$ErrorActionPreference` (not the `-ErrorAction` parameter) and can
+  suppress a statement-terminating error when the value is `SilentlyContinue`
+  or `Ignore`.
+
+```powershell
+function Test-Asymmetry {
+    [CmdletBinding()]
+    param()
+    $er = [System.Management.Automation.ErrorRecord]::new(
+        [System.InvalidOperationException]::new('test error'),
+        'TestError',
+        [System.Management.Automation.ErrorCategory]::InvalidOperation,
+        $null
+    )
+    $PSCmdlet.ThrowTerminatingError($er)
+}
+
+# -ErrorAction SilentlyContinue does NOT suppress the error:
+Test-Asymmetry -ErrorAction SilentlyContinue   # Error is still thrown
+
+# $ErrorActionPreference DOES suppress the error:
+$ErrorActionPreference = 'SilentlyContinue'
+Test-Asymmetry   # Error is silently suppressed, script continues
+$ErrorActionPreference = 'Continue'
+```
+
+> [!IMPORTANT]
+> `$ErrorActionPreference` cannot suppress errors that have
+> `SuppressPromptInInterpreter` set to `true` (such as
+> `ActionPreferenceStopException` from `-ErrorAction Stop` escalation),
+> errors inside PowerShell class methods, or `PipelineStoppedException`.
+> These always propagate regardless of the preference variable.
+
 ## Handling errors
 
 ### try/catch/finally
@@ -382,13 +433,14 @@ if (-not $config) {
 
 | Property | Non-terminating | Statement-terminating | Script-terminating |
 |----------|----------------|----------------------|-------------------|
-| Generated by | `Write-Error`, `WriteError()` | `ThrowTerminatingError()`, engine errors, `-ErrorAction Stop` | `throw` |
+| Generated by | `Write-Error`, `WriteError()` | `ThrowTerminatingError()`, engine errors, .NET method exceptions | `throw`, parse errors, `-ErrorAction Stop` escalation |
 | Scope of impact | Pipeline continues | Current statement stops; script continues | Call stack unwinds |
 | Caught by `catch` | No (unless escalated) | Yes | Yes |
 | Caught by `trap` | No (unless escalated) | Yes | Yes |
 | Added to `$Error` | Yes (unless `Ignore`) | Yes | Yes |
 | Sets `$?` to `$false` | Yes | Yes | Yes |
-| Affected by `-ErrorAction` | Yes | No (already terminating) | No |
+| Affected by `-ErrorAction` | Yes | No (`Break` only) | No |
+| Affected by `$ErrorActionPreference` | Yes | Yes (can suppress) | `throw`: No; escalated: No |
 
 ## See also
 
@@ -409,3 +461,4 @@ if (-not $config) {
 [06]: about_Try_Catch_Finally.md
 [07]: about_Trap.md
 [08]: about_Throw.md
+[09]: #the-erroractionpreference-asymmetry

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

@@ -388,9 +388,10 @@ The valid values are as follows:
   raised.
 - **Continue**: (Default) Displays the error message and continues executing.
 - **Ignore**: Suppresses the error message and continues to execute the
-  command. The **Ignore** value is intended for per-command use, not for use as
-  saved preference. **Ignore** isn't a valid value for the
-  `$ErrorActionPreference` variable.
+  command. Unlike **SilentlyContinue**, **Ignore** doesn't add the error
+  message to the `$Error` automatic variable. The **Ignore** value is also
+  valid for `$ErrorActionPreference`, where it suppresses both non-terminating
+  and statement-terminating errors without recording them in `$Error`.
 - **Inquire**: Displays the error message and asks you whether you want to
   continue.
 - **SilentlyContinue**: No effect. The error message isn't displayed and

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

@@ -47,10 +47,11 @@ it.
 PowerShell has three categories of errors. A _non-terminating error_ (generated
 by `Write-Error`) adds an error to the error stream without stopping execution
 and does not trigger `catch`. A _statement-terminating error_ (generated by
-`$PSCmdlet.ThrowTerminatingError()` or by `-ErrorAction Stop` escalation) stops
-the current statement but allows the script to continue at the next statement.
-A _script-terminating error_ (generated by `throw`) unwinds the entire call
-stack. Both statement-terminating and script-terminating errors can be caught by
+`$PSCmdlet.ThrowTerminatingError()`, engine errors, or .NET method exceptions)
+stops the current statement but allows the script to continue at the next
+statement. A _script-terminating error_ (generated by `throw`, parse errors, or
+`-ErrorAction Stop` escalation) unwinds the entire call stack. Both
+statement-terminating and script-terminating errors can be caught by
 `try/catch`. For a comprehensive reference, see
 [about_Error_Handling](/powershell/module/microsoft.powershell.core/about/about_error_handling).
 
@@ -74,7 +75,7 @@ function Start-Something
 }
 ```
 
-This creates a runtime exception that is a terminating error. It's handled by a `catch` in a
+This creates a runtime exception that is a script-terminating error. It's handled by a `catch` in a
 calling function or exits the script with a message like this.
 
 ```powershell
@@ -91,7 +92,7 @@ At line:1 char:1
 #### Write-Error -ErrorAction Stop
 
 I mentioned that `Write-Error` doesn't throw a terminating error by default. If you specify
-`-ErrorAction Stop`, `Write-Error` generates a terminating error that can be handled with a
+`-ErrorAction Stop`, `Write-Error` generates a script-terminating error that can be handled with a
 `catch`.
 
 ```powershell
@@ -103,7 +104,7 @@ Thank you to Lee Dailey for reminding about using `-ErrorAction Stop` this way.
 #### Cmdlet -ErrorAction Stop
 
 If you specify `-ErrorAction Stop` on any advanced function or cmdlet, it turns all `Write-Error`
-statements into terminating errors that stop execution or that can be handled by a `catch`.
+statements into script-terminating errors that stop execution or that can be handled by a `catch`.
 
 ```powershell
 Start-Something -ErrorAction Stop