Title: Clarify the intended behavior/documentation/terminology of terminating errors · Issue #4292 · PowerShell/PowerShell · GitHub
Open Graph Title: Clarify the intended behavior/documentation/terminology of terminating errors · Issue #4292 · PowerShell/PowerShell
X Title: Clarify the intended behavior/documentation/terminology of terminating errors · Issue #4292 · PowerShell/PowerShell
Description: For the larger context, see Our Error Handling, Ourselves - time to fully understand and properly document PowerShell's error handling. The documentation (about_Preference_Variables and about_Throw) only makes the distinction between non...
Open Graph Description: For the larger context, see Our Error Handling, Ourselves - time to fully understand and properly document PowerShell's error handling. The documentation (about_Preference_Variables and about_Throw...
X Description: For the larger context, see Our Error Handling, Ourselves - time to fully understand and properly document PowerShell's error handling. The documentation (about_Preference_Variables and about_T...
Opengraph URL: https://github.com/PowerShell/PowerShell/issues/4292
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Clarify the intended behavior/documentation/terminology of terminating errors","articleBody":"For the larger context, see [Our Error Handling, Ourselves - time to fully understand and properly document PowerShell's error handling](https://github.com/PowerShell/PowerShell-Docs/issues/1583).\r\n\r\n* The **documentation** (`about_Preference_Variables` and `about_Throw`) only makes the distinction between non-terminating and terminating errors, **neglecting to distinguish between the two fundamentally different types of terminating errors**:\r\n\r\n * **_statement_-terminating errors**, as generated by some cmdlets and by .NET exceptions\r\n * **_script_-terminating errors**, as generated with the `Throw` keyword or potentially by escalation via `-ErrorAction` or `$ErrorActionPreference`.\r\n\r\n* The **documentation mistakenly claims that `$ErrorActionPreference` exclusively applies to _non-terminating errors_**, whereas it controls the behavior of both types of terminating errors too.\r\n\r\nOn a personal note, the conflation of the two types of terminating errors in the documentation has caused me years of confusion.\r\n\r\n---\r\n\r\n\u003csup>The sample cmdlet used below that generates a terminating error is courtesy of @PetSerAl.\u003c/sup>\r\n\r\n### Statement-terminating errors\r\n\r\nSteps to reproduce\r\n------------------\r\n\r\n```powershell\r\n# Define New-TerminatingError cmdlet whose sole purpose is to generate a \r\n# statement-terminating error.\r\nAdd-Type '\r\n using System.Management.Automation; \r\n [Cmdlet(\"New\", \"TerminatingError\")]\r\n public class NewTerminatingErrorCmdlet : Cmdlet { \r\n protected override void ProcessRecord() { \r\n ThrowTerminatingError(new ErrorRecord(new System.Exception(), \"Error\", ErrorCategory.NotSpecified, null));\r\n } \r\n }' -PassThru | % Assembly | Import-Module\r\n\r\n# Per the documentation, this should only affect *non-terminating* errors.\r\n$ErrorActionPreference = 'Stop'\r\n\r\n# Should only terminate the statement (pipeline), not the script.\r\nNew-TerminatingError | % {} -End { 'end of pipeline' }\r\n\r\n'end of script'\r\n```\r\n\r\n\r\nExpected behavior\r\n-----------------\r\n\r\nNote: Expected based on the current documentation - arguably, the actual behavior makes more sense.\r\n\r\n```none\r\nNew-TerminatingError : Exception of type 'System.Exception' was thrown.\r\n...\r\nend of script\r\n```\r\n\r\nActual behavior\r\n---------------\r\n\r\n`$ErrorActionPreference = 'Stop'` did take effect for the pipeline-terminating error and aborted the script:\r\n\r\n```none\r\nNew-TerminatingError : Exception of type 'System.Exception' was thrown.\r\n...\r\n```\r\n---\r\n\r\n### Script-terminating errors\r\n\r\n```powershell\r\n# Per the documentation, this should only affect *non-terminating* errors.\r\n$ErrorActionPreference = 'SilentlyContinue'\r\n\r\n# Should abort the script, irrespective of the $ErrorActionPreference value, according\r\n# to the documentation.\r\nThrow \"I'm outta here\"\r\n\r\n'end of script'\r\n```\r\n\r\n\r\nExpected behavior\r\n-----------------\r\n\r\nThe script should be aborted, and the error message passed to `Throw` should be displayed.\r\n\r\n```none\r\nI'm outta here\r\n...\r\n```\r\n\r\nActual behavior\r\n---------------\r\n\r\n`$ErrorActionPreference = 'SilentlyContinue'` caused the `Throw` statement to be ignored.\r\n\r\nNote that, according to the documentation, `Ignore` is an invalid value for `$ErrorActionPreference` and should only be used with the `-ErrorAction` common _parameter_. \r\nHowever, it _is_ accepted and _somewhat_ takes effect: it ignores the `Throw` error, yet still records it in `$Error`.\r\n\r\n```none\r\nend of script\r\n```\r\n\r\n\r\nEnvironment data\r\n----------------\r\n\r\n```powershell\r\nPowerShell Core v6.0.0-beta.4 on macOS 10.12.5\r\nPowerShell Core v6.0.0-beta.4 on Ubuntu 16.04.2 LTS\r\nPowerShell Core v6.0.0-beta.4 on Microsoft Windows 10 Pro (64-bit; v10.0.15063)\r\nWindows PowerShell v5.1.15063.413 on Microsoft Windows 10 Pro (64-bit; v10.0.15063)\r\n```\r\n\r\n","author":{"url":"https://github.com/mklement0","@type":"Person","name":"mklement0"},"datePublished":"2017-07-18T23:34:53Z","url":"https://github.com/PowerShell/PowerShell/issues/4292"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:73315e6b-9a96-8b58-af62-54499edc1915 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | E474:3257C8:28FC70:37AFE9:6AFD5322 |
| html-safe-nonce | 79b97abfaa6fcb527abb772a24b2cbd4bad25e159ecf1f8d7a1fcb1d14f6ad8b |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFNDc0OjMyNTdDODoyOEZDNzA6MzdBRkU5OjZBRkQ1MzIyIiwidmlzaXRvcl9pZCI6Ijc1OTUyNTA4OTQyMzc0MjIzNzAiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 7a1285bf40b3803addd083af71fb1c8d73c9f6da0617d78f2249738b704d9b8f |
| hovercard-subject-tag | issue:243881922 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/PowerShell/PowerShell/4292/issue_layout |
| twitter:image | https://opengraph.githubassets.com/968c3a5c55c73ac8beed2d5e7031388da3ffbd3f83b36e834ea74584dc0be4e0/PowerShell/PowerShell/issues/4292 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/968c3a5c55c73ac8beed2d5e7031388da3ffbd3f83b36e834ea74584dc0be4e0/PowerShell/PowerShell/issues/4292 |
| og:image:alt | For the larger context, see Our Error Handling, Ourselves - time to fully understand and properly document PowerShell's error handling. The documentation (about_Preference_Variables and about_Throw... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | mklement0 |
| hostname | github.com |
| expected-hostname | github.com |
| None | 66653c2e55a6fff2930be1bdf07ee4f8aa137e3956d056c822563be6f878755e |
| turbo-cache-control | no-preview |
| go-import | github.com/PowerShell/PowerShell git https://github.com/PowerShell/PowerShell.git |
| octolytics-dimension-user_id | 11524380 |
| octolytics-dimension-user_login | PowerShell |
| octolytics-dimension-repository_id | 49609581 |
| octolytics-dimension-repository_nwo | PowerShell/PowerShell |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 49609581 |
| octolytics-dimension-repository_network_root_nwo | PowerShell/PowerShell |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | b6f01f7cb9f35f8c09949773241a3d49dd04b340 |
| ui-target | canary-2 |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width