Error Handling

## Two error kinds, not one Every confusing `try/catch` story in PowerShell starts with a split that most other shells and languages do not have. A **terminating error** stops the current pipeline immediately and unwinds the call stack until something handles it. `throw` raises one. An exception thrown by a .NET method you called is one. A cmdlet that hits a condition it cannot continue past raises one deliberately (internally through `ThrowTerminatingError`). A **non-terminating error** is a *report*. The cmdlet writes an `ErrorRecord` object to the error stream (stream 2), the host renders it in red, `$?` becomes `$false`, the record is appended to `$Error`, and execution continues with the next input item and the next statement. `Get-ChildItem` walking a large tree and hitting one unreadable directory is the canonical case: you want the other 999 directories, not an abort. Most cmdlet failures are non-terminating. That is the design, and it is why the default value of `$ErrorActionPreference` in a fresh session is `Continue`. ## Why catch is never entered `try/catch` is exception machinery: it only sees terminating errors. A non-terminating error unwinds nothing, so control never leaves the `try` block abnormally and the `catch` block is simply skipped. ```powershell try { Get-Item 'C:\does-not-exist' # non-terminating: prints red, keeps going 'still running' # this DOES print } catch { 'never printed' } ``` The red text makes it look like an exception fired. It did not. Candidates who have only ever seen exceptions in C# or Java assume that error output implies unwinding, and write `try/catch` wrappers that quietly handle nothing. ## The lever: -ErrorAction Stop `-ErrorAction` is a *common parameter*, available on every cmdlet and on advanced functions. Setting it to `Stop` converts that one call's non-terminating errors into terminating ones: ```powershell try { Get-Item 'C:\does-not-exist' -ErrorAction Stop } catch { "handled: $($_.Exception.Message)" } ``` The full set of values is worth knowing: - `Continue` — print the error, keep going. The default. - `SilentlyContinue` — keep going without printing, but the record is still added to `$Error` (and to `-ErrorVariable` if you asked for one). - `Ignore` — discard the error entirely; it is not recorded in `$Error`. Valid only as a `-ErrorAction` argument; assigning `Ignore` to `$ErrorActionPreference` is an error. - `Stop` — make it terminating. - `Inquire` — prompt the user. - `Break` — enter the debugger (PowerShell 7.x). ## The scope lever: $ErrorActionPreference `$ErrorActionPreference` is a preference variable applying to cmdlet calls that do not specify `-ErrorAction` themselves. It is scoped like any variable: setting it at the top of a script affects that script and code called from it, and it reverts when the scope ends — it does not permanently reconfigure the user's session. `-ErrorAction` on an individual call always wins over the preference. Many teams put `$ErrorActionPreference = 'Stop'` at the top of automation scripts to get fail-fast behaviour. That is a defensible convention, but understand what it does *not* cover: errors that are already terminating (unchanged), exceptions from .NET method calls (already terminating and always catchable), and external programs that merely exit non-zero — those are not error records at all. ## The cost of Stop on a multi-item cmdlet One consequence catches people out. A cmdlet given many inputs normally reports a non-terminating error per bad item and processes the rest. Under `-ErrorAction Stop` it aborts at the first failure, leaving the remaining items untouched: ```powershell # processes every reachable path, complains about the rest Get-Item $paths # stops dead at the first missing path Get-Item $paths -ErrorAction Stop ``` If you want every item attempted *and* a record of the failures, do not use `Stop` on the bulk call — either loop with a per-item `try/catch` and `-ErrorAction Stop` inside the loop, or keep going with `SilentlyContinue` and collect the records. ## finally `finally` runs whether or not an error occurred, and runs before the error continues propagating — the place for releasing a session, closing a file handle, or restoring a changed preference. A `try` needs only one of `catch` or `finally`; `try/finally` with no catch is a legitimate cleanup pattern that lets the error escape to a caller who knows what to do with it.