Http error 500 asp net core

Problems during the startup of an ASP.NET Core project on your production environment can be extremely hard to debug. In this article, I’ll guide you through where to look and possible solutions to common startup problems.

So, you spend days developing the next Facebook or Twitter in ASP.NET Core. Everything works out on your machine and after deploying your site to the production environment, all you get is this error in the browser:

As stated in the headline, the ASP.NET Core failed to startup. This means that something happened during the initialization of your app, why you won’t even be able to launch any of your web pages. This page is sometimes referred to as the White Screen of Death, a spin on the Blue Screen of Death in Windows and the Yellow Screen of Death in ASP.NET.

Here is a list of actions to run through, to help to figure out what went wrong. Not all of the actions may be applicable or even possible in your case.

Enable developer exception page

This is probably the fastest way to get some more details of the error happening. When working locally and errors happen, you get a much more detailed message in the browser. This is because of a piece of middleware part of ASP.NET Core named DeveloperExceptionPage. Open the Startup.cs file and locate the call to UseDeveloperExceptionPage:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
    }
    
    // ...
}

This is the code as it looks when creating a new ASP.NET Core from the default template. Yours may or may not look similar. The task here is to only use the developer exception page by replacing the code above with:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseDeveloperExceptionPage();
    
    // ...
}

This will show the developer exception page on both your local environment as well as production. This solution is only applicable before you get real users in your production environment. You never want to leak internal information from your application on an error page, when real users (and potential hackers) can access your site. Also, remember to switch back to the previous code once you have found the cause of the error.

Enable logging

Depending on how far ASP.NET Core has gotten before breaking down, you may be in luck and the error is logged as part of Microsoft.Extensions.Logging. To enable logging from your website, start by opening the Program.cs file and call the ConfigureLogging method like this:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
            webBuilder.ConfigureLogging((ctx, logging) =>
            {
            });
        });

Next, you will need to choose a destination for the log messages generated by ASP.NET Core. Since the error is happening on a remote web server, you will need some kind of persistent storage like a file, a database, a cloud logging service (like elmah.io), or similar. Let’s start with logging to the Windows Event Log by including the following code inside the action provided for the ConfigureLogging method:

logging.AddEventLog(options =>
{
    options.SourceName = "MyApp"; 
});

This will log all warnings and up to the Application log with a Source named MyApp. You can filter events using that source through the Event Viewer application in Windows.

In case you are hosting on Linux or Mac, the event log solution won’t be available. There, you will need to find an alternative (like a database). Microsoft.Extensions.Logging supports a range of logging targets either natively or through third-party packages available on NuGet.

I quickly want to mention the elmah.io integration for Microsoft.Extensions.Logging. Setting up logging only requires a few lines of code inside the ConfigureLogging method:

logging.AddElmahIo(options =>
{
    options.ApiKey = "API_KEY";
    options.LogId = new Guid("LOG_ID");
});

Once you have signed up for elmah.io, the real values to use instead of API_KEY and LOG_ID will be available through the elmah.io UI.

In some cases, problems occur before initializing the logging framework. ASP.NET Core provides some simple file logging through the web.config file. To enable file logging, add the following to your web.config file:

<system.webServer>
  <aspNetCore /* ... */ stdoutLogEnabled="true" stdoutLogFile=".logsstdout" />
</system.webServer>

This will create a log file named stdout followed by a rolling id in a logs folder in the root of the project. If the file is empty after running the failing endpoint, you can enable additional debug logging like this:

<system.webServer>
  <aspNetCore /* ... */>
    <handlerSettings>
      <handlerSetting name="debugFile" value=".logsaspnetcore-debug.log" />
      <handlerSetting name="debugLevel" value="FILE,TRACE" />
    </handlerSettings>
  </aspNetCore>
</system.webServer>

This will create a file named aspnetcore-debug.log in the same folder as explained above. For both the stdout and the aspnetcore-debug.log file, this is recommended for debugging problems on localhost only. In other words, don’t enable this in your production environment.

When running the site on your local machine, detailed log output similar to the debug log file specified above is available in the Output window inside Visual Studio. Make sure to select Debug in the Show output from the drop-down:

If running on Microsoft Azure, something similar can be viewed in the Application Event Logs tool available here:

Remote debug the application

ASP.NET Core supports remote debugging, meaning that you can attach a debugger running on your developer machine to the site running on the production environment.

To debug a remote site, you will need to carry out the following steps:

• Download the Remote tools matching your Visual Studio version here: https://learn.microsoft.com/en-us/visualstudio/debugger/remote-debugging-aspnet-on-a-remote-iis-computer?view=vs-2019#BKMK_msvsmon.
• Install Remote tools on the server running the webserver.
• Make sure to either disable the firewall on the webserver or allow incoming connections on port 4024.
• Launch Remote Debugger as Administrator (👈 important).

• Launch the website in Visual Studio on your developer machine and select Debug | Attach to process.
• Fill in the form like this, but replace the hostname with the name of the server running the webserver:

• Click the Attach button and you will be able to debug the remote application.

This was just a quick walkthrough. For the full documentation, check out Microsoft’s documentation here: https://learn.microsoft.com/en-us/visualstudio/debugger/remote-debugging-aspnet-on-a-remote-iis-computer?view=vs-2019.

Validate the appsettings.*.json files

A common problem for startup problems with ASP.NET Core is an invalid appsettings.json and/or appsettings.Production.json. It could be either a JSON syntax problem, a problem with the content within the config file, or a problem when transforming values from the appsettings.Production.json file into appsettings.json.

I will recommend you to grab both the appsettings.json and appsettings.Production.json (if any) files from the server and do the following for both files:

• Validate the JSON with this JSON Formatter and Validator.
• Validate the content of the JSON file with this Appsettings.json Validator.

Also, make sure to verify that the changes in the appsettings.Production.json file look correct using this Appsettings.json Transformation Tester.

See how we can help you monitor your website for crashes
Monitor your website

Startup errors in your ASP.NET Core middle-ware can cause real headaches. The 500/502 errors often don’t provide enough useful information to debug, often leaving us stumped for hours as we try to troubleshoot the root cause problem. While upgrading another piece of our site, we hit it again, but this time around, we let ourselves be sidetracked somewhat, and vowed to get to the bottom of the best ways to troubleshoot and prevent these errors going forward.

Troubleshooting

Let’s look at the most recent example, “HTTP Error 500.30 – ANCM In-Process Start Failure”. As you can see from the error below, there are no details, apart from statements that your application could not start – but we already know that, it’s why we are looking at an error message instead of the front page of our application.

Note that the error “HTTP Error 502.5 – Process Failure”, is very similar.

What these errors really mean, is that there is an unhandled error in your startup.cs or program.cs file, and it’s usually caused by a piece of middle ware. For us, it’s almost always related to Azure Key Vault access policies. When we run the app in Visual Studio on our laptop, our web page loads correctly, but as soon we deployed to our Azure web app, we receive the error. We verified this by removing our Visual Studio account from the Key Vault, and instantly received the same error locally. How can we troubleshoot an application in Azure when it works locally? Remember that due to the nature of these startup errors, they usually don’t show up in Application Insights either.

The best solution we’ve found, is to open the web app, and open “Advanced tools” to open Kudu.

Once in Kudu, we can open a “CMD” browser using the “Debug console” menu item.

Now we browse to our website wwwroot, “D:homesitewwwroot”, and run our application with “dotnet [your assembly name]”. This returns much more useful information. In the example below, we can see Key Vault did indeed return a forbidden permissions exception. Now we know enough to troubleshoot, and in this situation, we adding a missing access policy to allow our site to start working again.

Preventing

So how do we report these errors better in the future? As it turns out, startup error handling is purposely disabled. To show these errors, we need to add “CaptureStartUpErrors(true)” to our program.cs.

Now when we run our application, we see a much more useful error. Note that the ASPNETCORE_ENVIRONMENT variable must be set to “Development” to see this content, otherwise the regular 500.30 error will be shown. This is set to “Development” by default in Visual Studio, but “Release” by default in Azure.

Given that, we edit our startup code to show the useful error when deployed to our development Azure resource group, and the regular 500.30 error when in QA or production. We do this by adding an appsettings variable we will set to true in dev, but false in QA or Production. We also modify our deployment code to specifically set the ASPNETCORE_ENVIRONMENT variable to “Development” in Dev – leaving QA and Production in “Release”. Finally, we update our startup code, so that we can read in the the “CaptureStartErrors” variable from our appsettings, and use that to control whether or not we will see the errors.

Wrap-up

Today, we’ve learned about how to debug these difficult errors, and a better way to report on them in development.

References:

• 500.30/ 502.5 errors: https://odetocode.com/blogs/scott/archive/2018/07/16/7-tips-for-troubleshooting-asp-net-core-startup-errors.aspx
• Troublshooting Key Vault errors: https://stackoverflow.com/questions/51124843/keyvaulterrorexception-operation-returned-an-invalid-status-code-forbidden
• Application startup info: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-3.1
• How to capture startup errors: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/host/web-host?view=aspnetcore-3.1#capture-startup-errors
• Featured image credit: https://stackify.com/wp-content/uploads/2017/04/Best_Practices_for_Error_Handling_in_ASP-793×397.jpg