PowerShell live documentation

The stderr stream

Note: On GitHub Actions runners (where this site was generated), all of the output is different than on my (binyomen's) machine. Issue 29 tracks this. Best not to fully trust anything on this page until we have this figured out.

Basic case

When ErrorActionPreference is Continue, stderr in PowerShell Core behaves similarly to stderr in other shells. Most stderr output by commands you call will be sent directly to the PowerShell process's own stderr. It is interesting to note, however, that assigning the stderr command to a variable, casting it to Void, or piping it to Out-Null results in the stderr stream being received by stdout.

In PowerShell 2 and 5, the result is much different. Not only are stack traces printed out to stderr (except for the first print for some reason), nothing is printed to stdout. Everything is printed to stderr except redirecting to $null or a file and the redirect version of the variable, Void, and Out-Null cases.

Here is the output from writing directly to stderr. All versions print the same things, except that versions 2 and 5 have stack traces.

  1. $local:ErrorActionPreference = 'Continue'
  3. cmd /c 'echo printing to stderr 1 >&2'
  4. cmd /c 'echo printing to stderr 2 >&2'
Stderr
printing to stderr 1 
printing to stderr 2

Here we are redirecting to stdout, $null, and a file. Nothing prints the $null line. Versions 2 and 5 write the stdout line to stderr, while PowerShell Core writes it to stdout. All versions correctly write to the file, with versions 2 and 5 including stack traces.

  1. $local:ErrorActionPreference = 'Continue'
  3. cmd /c 'echo redirecting stderr to stdout >&2' 2>&1
  4. cmd /c 'echo redirecting stderr to $null >&2' 2> $null
  5. cmd /c 'echo redirecting stderr to a file >&2' 2> error.txt
  6. Write-Output "error.txt: $((Get-Content error.txt) -join `"`n`")"
Stdout
error.txt: cmd : redirecting stderr to a file 

At C:\Users\runneradmin\AppData\Local\Temp\pwsh-live-doc_06c9f3ae-517b-4de0-ac2a-5f27b0ee9bad\__script.ps1:6 char:16
+             cmd <<<<  /c 'echo redirecting stderr to a file >&2' 2> error.txt
    + CategoryInfo          : NotSpecified: (redirecting stderr to a file :String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError
 

error.txt: cmd : redirecting stderr to a file 
At C:\Users\runneradmin\AppData\Local\Temp\pwsh-live-doc_08486467-4d90-4c4b-9814-2fa40590e41e\__script.ps1:6 char:13
+             cmd /c 'echo redirecting stderr to a file >&2' 2> error.t ...
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (redirecting stderr to a file :String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError
 

redirecting stderr to stdout 
error.txt: redirecting stderr to a file
Stderr
cmd : redirecting stderr to stdout 
At C:\Users\runneradmin\AppData\Local\Temp\pwsh-live-doc_06c9f3ae-517b-4de0-ac2a-5f27b0ee9bad\__script.ps1:4 char:16
+             cmd <<<<  /c 'echo redirecting stderr to stdout >&2' 2>&1
    + CategoryInfo          : NotSpecified: (redirecting stderr to stdout :String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError
 

cmd : redirecting stderr to stdout 
At C:\Users\runneradmin\AppData\Local\Temp\pwsh-live-doc_08486467-4d90-4c4b-9814-2fa40590e41e\__script.ps1:4 char:13
+             cmd /c 'echo redirecting stderr to stdout >&2' 2>&1
+             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (redirecting stderr to stdout :String) [], RemoteException
    + FullyQualifiedErrorId : NativeCommandError

And finally here we redirect to a variable, cast to Void, and redirect to Out-Null. This test has huge variations between versions. All versions handle variables the same, assigning stderr to the variable if it's redirected and otherwise printing to stderr and leaving the variable blank.

Then it gets kinda weird. Versions 6.x and 7.0.3 print the non-redirected Void cast to stdout, while everything else prints it to stderr. The Out-Null test is the same, except 7.0.2 joins the 6.x/7.0.3 group.

  1. $local:ErrorActionPreference = 'Continue'
  3. $v = cmd /c 'echo assigning command result to a variable >&2'
  4. Write-Output "`$v: $v"
  5. $v = cmd /c 'echo assigning redirected command result to a variable >&2' 2>&1
  6. Write-Output "`$v: $v"
  7. [Void] (cmd /c 'echo casting stderr command to Void >&2')
  8. [Void] (cmd /c 'echo casting redirected stderr command to Void >&2' 2>&1)
  9. cmd /c 'echo piping stderr command to Out-Null >&2' | Out-Null
  10. cmd /c 'echo piping redirected stderr command to Out-Null >&2' 2>&1 | Out-Null
Stdout
$v: 
$v: assigning redirected command result to a variable
Stderr
assigning command result to a variable 
casting stderr command to Void 
piping stderr command to Out-Null

If you redirect stderr while ErrorActionPreference is Stop, an exception is generated. Here we have the same groupings, first writing directly to stderr. Since we aren't redirecting stderr, no exceptions are thrown except in versions 2 and 5, which seem to like throwing the second time you write to stderr for some reason.

  1. $local:ErrorActionPreference = 'Stop'
  3. try {
  4.     cmd /c 'echo printing to stderr 1 >&2'
  5. } catch {
  6.     Write-Output "Caught: $_"
  7. }
  9. try {
  10.     cmd /c 'echo printing to stderr 2 >&2'
  11. } catch {
  12.     Write-Output "Caught: $_"
  13. }
Stderr
printing to stderr 1 
printing to stderr 2

Then redirecting to stdout, $null, or a file all cause exceptions.

  1. $local:ErrorActionPreference = 'Stop'
  3. try {
  4.     cmd /c 'echo redirecting stderr to stdout >&2' 2>&1
  5. } catch {
  6.     Write-Output "Caught: $_"
  7. }
  9. try {
  10.     cmd /c 'echo redirecting stderr to $null >&2' 2> $null
  11. } catch {
  12.     Write-Output "Caught: $_"
  13. }
  15. try {
  16.     cmd /c 'echo redirecting stderr to a file >&2' 2> error.txt
  17. } catch {
  18.     Write-Output "Caught: $_"
  19. }
  21. Write-Output "error.txt: $((Get-Content error.txt) -join `"`n`")"
Stdout
Caught: redirecting stderr to stdout 
Caught: redirecting stderr to $null 
Caught: redirecting stderr to a file 
error.txt:

And finally redirecting to a variable, casting to Void, or redirecting to Out-Null throw exceptions for all tests where stderr is redirected to stdout (which makes sense, since redirecting to stdout by itself throws).

For all versions, assigning to a variable without redirection leaves the variable empty and prints to stderr. All other operations throw except in version 7.0, where casting stderr to Void prints to stderr instead.

  1. $local:ErrorActionPreference = 'Stop'
  3. try {
  4.     $v = cmd /c 'echo assigning command result to a variable >&2'
  5.     Write-Output "`$v: $v"
  6. } catch {
  7.     Write-Output "Caught: $_"
  8. }
  10. try {
  11.     $v = cmd /c 'echo assigning redirected command result to a variable >&2' 2>&1
  12.     Write-Output "`$v: $v"
  13. } catch {
  14.     Write-Output "Caught: $_"
  15. }
  17. try {
  18.     [Void] (cmd /c 'echo casting stderr command to Void >&2')
  19. } catch {
  20.     Write-Output "Caught: $_"
  21. }
  23. try {
  24.     [Void] (cmd /c 'echo casting redirected stderr command to Void >&2' 2>&1)
  25. } catch {
  26.     Write-Output "Caught: $_"
  27. }
  29. try {
  30.     cmd /c 'echo piping stderr command to Out-Null >&2' | Out-Null
  31. } catch {
  32.     Write-Output "Caught: $_"
  33. }
  35. try {
  36.     cmd /c 'echo piping redirected stderr command to Out-Null >&2' 2>&1 | Out-Null
  37. } catch {
  38.     Write-Output "Caught: $_"
  39. }
Stdout
$v: 
Caught: assigning redirected command result to a variable 
Caught: casting redirected stderr command to Void 
Caught: piping redirected stderr command to Out-Null
Stderr
assigning command result to a variable 
casting stderr command to Void 
piping stderr command to Out-Null

Class methods

This behavior has interesting consequences for class methods (See Method stdio). Since non-void methods automatically suppress stdio, it's as if they were redirecting stderr to $null, so printing to stderr within a non-void method will produce an exception when ErrorActionPreference is Stop.

Void methods don't suppress stderr, even though they suppress stdout. Despite this, Void methods throw the first time stderr is printed in version 5, and the second time in PowerShell Core.

  1. $local:ErrorActionPreference = 'Stop'
  3. class C {
  4.     [String] StringFunc() {
  5.         cmd /c 'echo StringFunc: printing to stderr 1 >&2'
  6.         cmd /c 'echo StringFunc: printing to stderr 2 >&2'
  7.         return 'some string'
  8.     }
  10.     [Void] VoidFunc() {
  11.         cmd /c 'echo VoidFunc: printing to stderr 1 >&2'
  12.         cmd /c 'echo VoidFunc: printing to stderr 2 >&2'
  13.     }
  14. }
  16. $c = [C]::new()
  18. try {
  19.     $c.StringFunc()
  20. } catch {
  21.     Write-Output "Caught: $_"
  22. }
  24. try {
  25.     $c.VoidFunc()
  26. } catch {
  27.     Write-Output "Caught: $_"
  28. }
Stdout
Caught: StringFunc: printing to stderr 1
Stderr
VoidFunc: printing to stderr 1 
VoidFunc: printing to stderr 2

When ErrorActionPreference is Continue, I'm honestly not sure what's going on. For GitHub Actions runners, it seems the Void function prints to stdout in PowerShell Core and not in version 5. The second Void print makes it to stderr on its own in version 5, but all other prints starting with "Note" seem to be compressed onto a single line.

  1. $local:ErrorActionPreference = 'Continue'
  3. class C {
  4.     [String] StringFunc() {
  5.         cmd /c 'echo Note: This line only seems to print on GitHub Actions >&2'
  6.         cmd /c 'echo StringFunc: printing to stderr 1 >&2'
  7.         cmd /c 'echo StringFunc: printing to stderr 2 >&2'
  8.         return 'some string'
  9.     }
  11.     [Void] VoidFunc() {
  12.         cmd /c 'echo VoidFunc: printing to stderr 1 >&2'
  13.         cmd /c 'echo VoidFunc: printing to stderr 2 >&2'
  14.     }
  15. }
  17. $c = [C]::new()
  19. try {
  20.     $c.StringFunc()
  21. } catch {
  22.     Write-Output "Caught: $_"
  23. }
  25. try {
  26.     $c.VoidFunc()
  27. } catch {
  28.     Write-Output "Caught: $_"
  29. }
Stdout
some string
Stderr
Note: This line only seems to print on GitHub Actions StringFunc: printing to stderr 1 StringFunc: printing to stderr 2 VoidFunc: printing to stderr 1 
VoidFunc: printing to stderr 2

See also

This PowerShellTraps page is also an incredible source for information about stderr.