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
- The first line names the exception type and its message: that is what a bug report should quote.
- Each at line is a frame, from the throw outward. The top frame is where it was thrown, the last is the entry point.
- in /path/Program.cs:line 2 is there because the build produced a PDB next to the assembly; a build without one prints method names and no line numbers.
- InnerException appears below the outer exception with the line --- End of inner exception stack trace --- between the two, which is where a wrapped error shows its cause.
Exercises
- Wrap the throw in a method and see which frame is first in the trace.
- Throw an exception with an inner exception and find the End of inner exception line.
- Set Environment.ExitCode = 0 after an exception was caught and check the status of the run.
- 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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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