Troubleshooting .NET Core Startup Errors

"An unexpected error occurred" is the minimum informative error message of every error message. It is as if cosmic rays have converted your predictable computing machinery into a white noise generator.

Startup errors with ASP.NET Core don't tell much information either, at least not in a production environment. Here are tips for understanding and fixing those errors.

  1. There are two types of startup errors.

Unhandled exceptions are originating outside of the Startup class, and exemptions from inside of Startup. These two errors can behave differently and may need different troubleshooting methods.

  1. ASP.NET Core will solve exceptions from inside the Startup class.

If code in the Configure methods or ConfigureServices throws an exception, the framework will catch the exception, and it will still execute.

Although the process still runs after the exception, every incoming request will produce a 500 response with the message "An error occurred while starting the application."

Two additional pieces of information regarding this condition:

- If you want the process to the breakdown in that condition, call CaptureStartupErrors on the web host builder and give the false value.

- In a result environment, the "error occurred" message is only the detail you'll see in a web browser. The framework follows the method of not giving away error details in the result because error details may provide an attacker so much information. You can update the environment setting using the environment variable ASPNETCORE_ENVIRONMENT but see the next two tips first. You don't have to change the entire situation to see more error details.

  1. Set detailed errors in code to see a stack trace.

The bit of code allows for the detailed error message, still in production, so use with care.

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>


           .CaptureStartupErrors(true) // the default

           .UseSetting("detailedErrors", "true")


  1. rather, then set the ASPNETCORE_DETAILEDERRORS environment variable.

Change the value to true, and you'll also see a stack trace, even in production, so be alert.

  1. Unhandled exceptions external of the Startup class will eliminate the process.

Possibly you have code inside of Program.cs to run schema migrations or perform other initialization tasks that fail, or maybe the application cannot bind to the required ports. If you are running with IIS, this is the case where you'll see a generic 502.5 Process Failure error message.

These kinds of errors can be a bit more challenging to track down, but the following two tips will help.

  1. For IIS, enable standard output logging in web.config.

If you are cautiously logging using other tools, you may be able to get a result there, too, but if everything fails, ASP.NET will print exception messages to stdout by default. By keeping the log flag true, and making the output directory, you'll have a file with exception information and a stack trace internally to help track down the problem.

It shows the web.config file created by .net publish and is usually the config file in use when hosting .NET Core in IIS. The property to update is the stdoutLogEnabled flag.



    <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />


  <aspNetCore processPath="dotnet" arguments=".\codes.dll"

              stdoutLogEnabled="true" stdoutLogFile=".\logs\stdout" />


Important: Surly to build the logging output directory


 Make sure to turn logging off after problem is solved.