PSCmdlet.ThrowTerminatingError() does not result in a terminating error

[colinblaise]

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest released version
• Search the existing issues.
• Refer to the FAQ.
• Refer to Differences between Windows PowerShell 5.1 and PowerShell.

Steps to reproduce

Run the attached repro project.

powershelltest.zip

Expected behavior

An exception should occur in the pipeline as a terminating error

Actual behavior

A terminating error is not thrown

Error details

No response

Environment data

Name                           Value
----                           -----
PSVersion                      7.3.4
PSEdition                      Core
GitCommitId                    7.3.4
OS                             Microsoft Windows 10.0.22000
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Visuals

No response

[jhoneill]

It does throw a terminating error. It's just that terminating errors are treated as caught and handled when really they are not, if the code that calls whatever throws the error has the default error action preference. If you wrap the call in try {} catch {} or if you change e.a.p, the error acts like most people would expect it to.

Paging @mklement0 who has all the details of this at his fingertips :-) Sadly V1 designed things this way to act like a batch language, and it's less than great but we're probably stuck with it.

[colinblaise]

Thanks for the response. Yeah, I understand it's just how it was designed. It's just bizarre that "throw" when called directly in PowerShell does not take into account e.a.p, but "throw" in a C# PSCmdlet does.

[jhoneill]

We'll get into angels on the head of pin, but ... Throw produces errors which don't consider themselves handled by printing the message (which is the default for e.a.p) but if an $errorActionPreference setting of silentlyContinue inherits into (or is explicitly set for) a function containing throw the throw is considered to be handled there and then - which can have unexpected consequences. throw was designed for one script to throw the anchors out and it's caller, and it's caller's caller etc.

ThrowTerminatingError was designed for a (compiled) cmdlet to say "er, we got a problem, we're bailing, you might want to think about aborting" - the caller's e.a.p decides what happens (so -errorAction doesn't change anything) and the default action preference is "yeah there was an alarm, keep going".

[SeeminglyScience]

ThrowTerminatingError generates a pipeline terminating error rather than a call stack terminating error. Only the pipeline that the command is in is terminated, subsequent statements will continue. ErrorAction does not have any effect on pipeline terminating errors. Also a binary cmdlet cannot generate call stack terminating errors, that's not supposed to be the job of a command.

[mklement0]

@colinblaise, unofficial terms have been coined - which are hopefully descriptive enough, even though they're not fully technically correct - to help conceptualize the behavior:

In effect, PowerShell has two types of terminating behavior, as implied by @SeeminglyScience's comment:

• Statement-terminating errors (pipeline-terminating errors), which - by default - continue execution (at the next statement/pipeline).

• Script-terminating (call-stack-terminating, runspace-terminating), which - by default - are fatal.

Unfortunately, this crucial distinction is still missing from the documentation.

I've attempted to summarize the inconsistencies and complexities of PowerShell's error handling in the following issue, which has become a live document of sorts (do tell us if something doesn't look right):

• Our Error Handling, Ourselves - time to fully understand and properly document PowerShell's error handling MicrosoftDocs/PowerShell-Docs#1583

[jhoneill]

@mklement0 I know you have used "Statement terminating" for some time , and it is sometimes difficult to get people to differentiate between a language statement (for, while etc.) a command (alias, function, cmdlet, external program) and a pipeline (command or value(s) or a pipeline [but not for or similar statements], optionally piped into a command)

The code below shows that ThrowTerminatingError stops commands earlier in the pipeline, i.e. it is pipeline terminating, but it does not stop a foreach statement

function foo {
    [CmdletBinding()]
    param (
        [Parameter(ValueFromPipeline=$true,Position=0)]
        $p
    )
    process {
        if ($p -gt 5) {
            $er = [System.Management.Automation.ErrorRecord]::new("Invalid P","99",[System.Management.Automation.ErrorCategory]::InvalidData, $null )
            $pscmdlet.ThrowTerminatingError($er)
        }
        else     { $p }
    }
}


function bar {
    [CmdletBinding()]
    param (
        [Parameter(ValueFromPipeline=$true,Position=0)]
        $p
    )
    process {
    Write-host "$p in bar"
     $p 
    }
}


 1..7 | bar | foo | foreach {$_ * $_}
 

foreach ($v in (1..7)) {foo $v}

I wonder if it might be better to stick to "Pipeline terminating" for these errors ?

[mklement0]

tl;dr

• As long as an official name is chosen and documented, I'd be fine with pipeline-terminating, though my concern is that end users don't think of expressions such as 1 / 0 or $x = [int]::Parse('foo') as pipelines, and, despite the potential confusion with language statement, there is precedent for naming the smallest unit of execution a statement.

• Plus, if such an error occurs in the conditional part of a language statement, it does terminate the entire construct; e.g.:

# The inputs are evaluated up front, and the statement-terminating
# error terminates the entire compound statement, without entering the loop body.
foreach ($i in 1, (1/0), 3) {
    $i
}

---

@jhoneill, let me start with what I think is the fundamental problem:

• Fundamental concepts are missing from the documentation.
• When they are touched upon, they aren't discussed as such and aren't given official names.

Things have improved over the years (think delay-bind script parameters, calculated properties and, most recently, member-access enumeration), though in the realm of error handling the documentation is still woefully lacking.

Once official names have been established and concepts are documented using those names, how intuitive those names are isn't all that important anymore - although intuitively obvious names are certainly preferable.

---

As for statement-terminating vs. pipeline-terminating:

I originally picked statement-terminating based on this homegrown taxonomy of PowerShell execution units.

While the term language statement for constructs such as foreach, while, ... is somewhat established:

• it isn't used in the conceptual about_Language_Keywords help topic, where the term statement in isolation is used to refer to a statement in the sense that I had in mind: as the smallest unit of execution, as evidenced by referring to the execution units that such a language statement is composed of; e.g, the sample code for continue shows a while command composed of <statements> parts.
  And while you can make the argument that this is just a recursive definition, this just shifts the goal post: ultimately, there must be unit of execution other than a language statement that they are composed of.

• by contrast, topics such as about_While do talk about language statements but also refer to their constituent parts as statements.

In short: the distinction is fuzzy, but my guess is that the term statement in isolation - without the language qualifier - will be understood to mean the smallest unit of execution, be it a single expression or a single command / command pipeline (possibly in combination with an assignment) - as opposed to a whole "group" of such statements, as enclosed in a keyword-based flow-control construct such as while (I've used the word compound statement in the past, which strikes me as conceptually clearer, but it seems that language statement has won out.)

[jhoneill]

@jhoneill, let me start with what I think is the fundamental problem:

• Fundamental concepts are missing from the documentation.
• When they are touched upon, they aren't discussed as such and aren't given official names.

We are in complete agreement here.

This issue has been marked as answered and has not had any activity for 1 day. It has been closed for housekeeping purposes.