Unhandled exceptions and exit codes

The text of an unhandled exception

An exception that reaches the top of the program without a catch stops it. The runtime prints the type, the message and the frames on the standard error stream, and the process ends through an abort. This is the whole program:

Console.WriteLine("before"); throw new InvalidOperationException("boom");

dotnet run

before
Unhandled exception. System.InvalidOperationException: boom
   at Program.<Main>$(String[] args) in /tmp/exception-demo/Program.cs:line 2

before went to the standard output and the rest to the standard error, which is why a terminal shows them in this order. The path after in is the source file of the build on the machine that ran it, so a reader who builds the same program sees their own folder there. The exit status is 134.

AppDomain.UnhandledException

The runtime raises one event before it prints that text. A handler can log the error, but it cannot stop the crash: after the handler returns, the process still aborts.

AppDomain.CurrentDomain.UnhandledException += (sender, e) => { var error = (Exception)e.ExceptionObject; Console.WriteLine($"handler saw {error.GetType().Name}: {error.Message}"); }; Console.WriteLine("before"); throw new InvalidOperationException("boom");

dotnet run

before
handler saw InvalidOperationException: boom
Unhandled exception. System.InvalidOperationException: boom
   at Program.<Main>$(String[] args) in /tmp/exception-demo/Program.cs:line 8

The handler line came from the program and the two below it from the runtime. To change the outcome, a handler must call Environment.Exit with a status of its own, which the next part covers, and even then the cleanup of the frames that were unwound does not happen: this event is a last look, not a rescue. The exit status of this run is 134 as well.

The exit status

The shell reports the death of the process as status 134: 128 plus 6, the signal number of SIGABRT. That is the real status of the two programs above, and a script that checks a build step sees it as a failure without knowing anything about .NET.

A program that ends normally has whatever status it chose. The default is 0; a deliberate one is set with Environment.ExitCode or by returning a number from Main:

Environment.ExitCode = 3; Console.WriteLine("work done");

dotnet run

work done

The output looks like a success and the exit status is 3. That is the combination to check for in a script: dotnet run; echo $? prints 3, and a tool that runs the program sees a failure while a reader of the log sees a normal line. The exit status of this run is 3. The exit status is the contract with the caller; the text is for the person.

Reading a stack trace

Exercises

  1. Wrap the throw in a method and see which frame is first in the trace.
  2. Throw an exception with an inner exception and find the End of inner exception line.
  3. Set Environment.ExitCode = 0 after an exception was caught and check the status of the run.
  4. Return an int from a static int Main instead of setting the property and compare the two programs.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What exit status does an unhandled exception give on this platform?

    Answer

    134, from the abort signal

    The process is aborted, and the shell reports 128 plus the SIGABRT number, which is 134.

  2. What can an AppDomain.UnhandledException handler do?

    Answer

    Log the error, but not stop the crash

    The event is a last look; after the handlers the process still terminates.

  3. What does this program print? Environment.ExitCode = 7; Console.WriteLine("ok");

    Answer

    ok

    The property sets the status the process ends with, which is 7, and the line prints normally.

  4. Where does the unhandled exception text go?

    Answer

    To the standard error stream

    The runtime writes the trace to stderr, which is why a redirect of stdout can miss it.

  5. Which line of a stack trace names the error?

    Answer

    The first one, with the type and the message

    The type and message are the part to quote in a bug report.

  6. What does this program print? Console.WriteLine("done"); return 2;

    Answer

    done

    The line prints and the int returned becomes the exit status of the process, which is 2.

  7. Why does the trace show a file and a line number?

    Answer

    The build wrote a PDB with the source positions

    The debug symbols next to the assembly carry the mapping from code offsets to source lines.

  8. What does the number in at Program.<Main>$(String[] args) describe?

    Answer

    The generated method that holds the top-level statements

    Top-level statements are compiled into a generated Main, and the name shows it.

  9. A script runs a program and checks only whether it printed an error line. What does it miss?

    Answer

    A non-zero exit status with normal-looking output

    The third program prints a normal line and exits with 3, which a text check cannot see.

  10. What does dotnet run; echo $? show after an unhandled exception?

    Answer

    The runtime text and then 134

    dotnet passes the status of the program through, and the abort gives 134.

The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image