Add about_Error_Handling and fix error terminology across docs#12890
Add about_Error_Handling and fix error terminology across docs#12890sdwheeler merged 10 commits intoMicrosoftDocs:mainfrom
Conversation
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit bf58d3d: ✅ Validation status: passed
For more details, please refer to the build report. |
SufficientDaikon
force-pushed
the
docs/error-handling-overhaul
branch
from
bf58d3d to
94b6c6e
Compare
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 94b6c6e: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 397f608: ✅ Validation status: passed
For more details, please refer to the build report. |
SufficientDaikon
force-pushed
the
docs/error-handling-overhaul
branch
from
397f608 to
94b6c6e
Compare
SufficientDaikon
requested review from
michaeltlombardi and
sdwheeler
as code owners
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 94b6c6e: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 020931e: ✅ Validation status: passed
For more details, please refer to the build report. |
reference/7.6/Microsoft.PowerShell.Core/About/about_CommonParameters.md
Outdated
Show resolved
Hide resolved
reference/7.6/Microsoft.PowerShell.Core/About/about_Error_Handling.md
Outdated
Show resolved
Hide resolved
reference/7.6/Microsoft.PowerShell.Core/About/about_Error_Handling.md
Outdated
Show resolved
Hide resolved
reference/7.6/Microsoft.PowerShell.Core/About/about_Preference_Variables.md
Outdated
Show resolved
Hide resolved
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit fd972ca: ✅ Validation status: passed
For more details, please refer to the build report. |
|
@mklement0 anything else? |
This comment was marked as resolved.
This comment was marked as resolved.
@mkelement0 some of mine too |
|
A few high-level observations, which in part may require corrections in multiple places:
# NON-advanced script block: *script*-terminating error ('after' doesn't print)
& { param() $ErrorActionPreference = 'Stop'; gi -nosuch }; 'after'
# ADVANCED script block: *statement*-terminating error ('after' prints).
& { [cmdletbinding()]param() $ErrorActionPreference = 'Stop'; gi -nosuch }; 'after' |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 0808e1d: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
@mklement0 — Thank you for this. These are exactly the kinds of corrections that make me glad I opened this PR rather than leaving the docs as they were. 1. You're right — I verified this and my claim ("regardless of 2. Confirmed — 3. Advanced vs. non-advanced escalation The escalation section now documents this distinction with your exact example pattern. I also changed the All three fixes pushed in bc5e604 and a1c3c06. I'd really value a follow-up pass from you on the revised escalation section — your source-level knowledge of these paths is what makes this documentation accurate rather than "close enough." generated by opus. |
|
Learn Build status updates of commit a1c3c06: ✅ Validation status: passed
For more details, please refer to the build report. |
|
@mklement0 sorry about my comments being generated by ai, i'm working on dialing it down anyhow, i appreciate your replies and engagment it's really helpful for me to make the PR better, so yea i'll only tag you from now on IF i need input, otherwise i'll just keeping working on this till it's good enough to be merged. have a good weekend! |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 598d241: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 62b791b: ✅ Validation status: passed
For more details, please refer to the build report. |
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 MicrosoftDocs#1583
- -ErrorAction Stop promotes to script-terminating, not statement-terminating - $ErrorActionPreference applies to both non-terminating and statement-terminating errors (unlike -ErrorAction parameter) - $ErrorActionPreference = 'Ignore' is now accepted (remove outdated caveat) - Native command non-zero exit emits non-terminating NativeCommandExitException Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…se 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>
…d escalation Three corrections based on mklement0's review: 1. throw CAN be suppressed by $ErrorActionPreference when set to SilentlyContinue or Ignore. Removed the incorrect claim that throw is "always" script-terminating "regardless of $ErrorActionPreference". Also documented that -ErrorAction on advanced functions translates to a scope-local $ErrorActionPreference, so it suppresses throw too. 2. Added NOTE that $ErrorActionPreference = 'Ignore' still records terminating errors in $Error. Ignore only prevents $Error recording for non-terminating errors. 3. Escalation section now documents the advanced vs. non-advanced distinction: $ErrorActionPreference = 'Stop' produces script-terminating errors in non-advanced contexts, but statement-terminating errors in advanced contexts ([CmdletBinding()]). Summary table updated to reflect both contexts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ript-terminating Per mklement0 feedback, -ErrorAction Stop escalation scope depends on whether the context is advanced ([CmdletBinding()]) or non-advanced. Changed about_CommonParameters.md and ErrorAction table to say "terminating error" generically, with escalation section providing the full advanced vs. non-advanced explanation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- 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>
- About.md: Update throw index to "script-terminating error by default" - about_Automatic_Variables: Qualify $Error/Ignore as non-terminating only - about_CommonParameters: Qualify Ignore bullet as non-terminating only Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- About.md: Add missing about_Error_Handling entry to topic index - About.md: Update about_Trap and about_Try_Catch_Finally descriptions to say "statement-terminating and script-terminating errors" - about_Try_Catch_Finally.md: Fix [07] link text to match target heading - Update ms.date on about_Trap, about_CommonParameters, about_Preference_Variables, everything-about-exceptions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
sdwheeler
force-pushed
the
docs/error-handling-overhaul
branch
from
62b791b to
8ebe0df
Compare
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 8ebe0df: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
@SufficientDaikon Thank you very much for your work here. This has been a tough subject to organize. You did a great job presenting the information and standardizing the terminology. In commit 087687f I made editorial changes. Most were formatting. Some wording changes for style and voice. But nothing factual should have changed. I will now work on copying these changes to the other versions before we merge. |
|
Learn Build status updates of commit 087687f: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 8cc25cb: ✅ Validation status: passed
This comment lists only the first 25 files in the pull request. |
|
@sdwheeler aw, it's comments like that that make me feel that all the copilot premium requests I spent on this were worth it. Do you need anything else from me or is this done? |
It's done and merged. If you find any errors, please feel free to submit fixes 😄. |
3 participants
Creates a comprehensive
about_Error_Handlingreference topic and corrects factual errors across eight existing files. Every correction is cited against the PowerShell engine source code.Btw, this entire PR is generated by opus, so do keep that in mind as you read through
At a glance
flowchart TD A["Error occurs"] --> B{"Error type?"} B -->|"WriteError()"| C["Non-terminating"] B -->|"ThrowTerminatingError()"| D["Statement-terminating"] B -->|"throw keyword"| E["Script-terminating"] C --> F["Pipeline continues"] D --> G["Statement stops, script continues"] E --> H["Call stack unwinds"] style C fill:#E7E6E6,color:#333 style D fill:#FFF2CC,color:#333 style E fill:#F8D7DA,color:#333 style F fill:#E2EFDA,color:#333 style G fill:#FFF2CC,color:#333 style H fill:#F8D7DA,color:#333The existing docs use "terminating error" as one category. The engine has three. This PR fixes that — and several other inaccuracies discovered along the way.
What this PR corrects
Warning
These are factual corrections, not style changes. Each one fixes a claim that contradicts the engine's actual behavior.
1. "ErrorAction has no effect on terminating errors"
about_CommonParametersandabout_Preference_Variablessaid-ErrorAction/$ErrorActionPreferencehave "no effect on terminating errors"-ErrorAction Stopescalates non-terminating errors to terminating errors by generating anActionPreferenceStopException_WriteErrorSkipAllowCheck2. "
throwalways generates a script-terminating error"about_Throwdescribedthrowas unconditionally script-terminating$ErrorActionPreference = 'SilentlyContinue'or'Ignore'can suppressthrow— execution continues at the next statementCheckActionPreferenceintercepts before rethrow3. "
Ignoreprevents$Errorrecording"about_Preference_Variables,about_CommonParameters, andabout_Automatic_VariablesimpliedIgnoreuniversally prevents$ErrorrecordingIgnoreonly prevents$Errorrecording for non-terminating errors. Terminating errors (including suppressedthrow) still record in$ErrorAppendDollarErrorskip is in non-terminating path only4.
-ErrorAction Stopescalation type-ErrorAction Stopas producing one specific error type[CmdletBinding()])SuppressPromptInInterpreterflag5. Code bug in
about_Try_Catch_Finally$tempPathwas never defined — the variable is$tempFile(line 261).What this PR adds
New topic:
about_Error_HandlingA ~500-line reference that didn't exist before. Covers:
$?,$Error,$LASTEXITCODE— when each updates and when it doesn't-ErrorActionvaluesStopturns non-terminating into terminating, and why it differs in advanced vs non-advanced contexts$ErrorActionPreferenceasymmetry-ErrorActiononly affects non-terminating [SRC-1] [SRC-3]throwsuppression$ErrorActionPreferencecan suppressthrow, and theIgnore/$Errorcaveat [SRC-2]try/catch/trapPropagateExceptionsToEnclosingStatementBlockflag [SRC-4]Write-ErrorvsThrowTerminatingError()vsthrowin functionsFiles changed
about_Error_Handling.mdabout_CommonParameters.mdIgnore/$Error; explainStopescalationabout_Preference_Variables.md$ErrorActionPreferencefix; correctIgnoredescriptionabout_Throw.mdIgnore/$ErrorNOTEabout_Try_Catch_Finally.md$tempPathbugabout_Trap.mdabout_Automatic_Variables.md$Error/Ignoreas non-terminating onlyAbout.mdabout_Error_Handlingto topic index; update 3 descriptionseverything-about-exceptions.md-ErrorAction Stopterminology to "terminating" (context-dependent)Source citations
Every factual claim links back to engine source. Here's the index:
MshCommandRuntime.csWriteError()checks-ErrorAction;StopcreatesActionPreferenceStopException;ThrowTerminatingError()does NOT check-ErrorAction(exceptBreak)MiscOps.csL1744-1782CheckActionPreferencecan suppressthrowwhen$ErrorActionPreference=SilentlyContinue/IgnoreMiscOps.csL1564-1631FindMatchingHandlerunwrapsActionPreferenceStopException;SuppressPromptInInterpretercontrols escalation typeCompiler.csL5244-5260PropagateExceptionsToEnclosingStatementBlock = trueinsidetryblocksTerminology precedent already in this repo
The terms "statement-terminating" and "script-terminating" already exist in
reference/7.6/:about_Calculated_Properties.md(line 504): "statement-terminating and script-terminating errors"about_Pipeline_Chain_Operators.md(lines 122, 205): "script-terminating error"about_Pwsh.md(lines 117, 201): "script-terminating (runspace-terminating) error"This PR makes all error-related docs consistent with vocabulary the repo already uses.
Scope and limitations
Note
What this PR does NOT do — and what I'm uncertain about.
reference/7.6/about_ topics, the index, and the conceptual deep-dive articleWrite-Error.md,Set-StrictMode.md, and a few other cmdlet pages use "terminating error" without qualification. Fixing those is a different review surface (cmdlet docs vs conceptual docs) and I think it's better as a separate PR — but I could be wrong. Open to guidance.FullLanguagemode. I haven't verified whetherConstrainedLanguagemode changes any of these behaviors. The engine source suggests it doesn't, but I want to be transparent that I haven't tested it.throwsuppression) may behave differently. The 5.1 docs should be verified independently before backporting.Related
about_Error_Handling)PR Checklist