In this article, we will learn about the HTTP Error 500.31 generated by IIS, what causes it, and how we can solve it.

Let’s start.

HTTP Error 500.31 Description

We’ve just published our first .NET Core application on the IIS, and we’re eager to see how it looks. We navigate to the web server link and… oh no, we see this error:

IIS HTTP Error 500.31

The error is of type 500, meaning it is a server-side error, preventing the application from correctly serving HTTP requests. More specifically the issue is represented by our .NET Core configuration.

Support Code Maze on Patreon to get rid of ads and get the best discounts on our products!
Become a patron at Patreon!

Possible Causes for the HTTP Error 500.31

Let’s look at the most common reasons that may trigger this error.

Missing .NET Core Hosting Bundle

The .NET Core Hosting Bundle is a crucial package that provides the infrastructure needed for the IIS to host and run .NET Core applications. With each version of .NET Core, we get a corresponding Hosting Bundle that includes the following components:

  • .NET Core
  • .NET Core Runtime
  • ASP.NET Core Module

That’s all we need to run our application successfully.

To quickly check if our machine has the bundle installed we can look inside the Control Panel:

Windows-Hosting-ControlPanel installation needed for fixing HTTP Error 500.31

There it is!

Another way to confirm the presence of the .NET Core Hosting Bundle is through the Registry Editor. We can find it by typing the regedit command in the Windows Search box and then navigate to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Updates\.NET path:

Windows-Server-Hosting-Regedit

Don’t worry if the bundle is not present, we’ll cover the installation steps in the next section.

Incompatible .NET Core Runtime Versions

Next, let’s analyze another potential cause that can trigger our error, the incompatibility between the .NET Core Runtime version used by our application and the one installed on the machine running the IIS.

.NET Core follows the backward compatibility principle, meaning that if our machine has installed a newer version, it will run applications built with an older version. This applies starting from .NET Core 3.1 and onwards.

However, if our application is developed using a newer version than the one installed on our machine, we are likely to encounter the HTTP Error 500.31.

To check the installed .NET Core Runtimes we can run dotnet –info in Command Prompt or PowerShell:

PS C:\Users\Alin> dotnet --info
.NET SDK:
 Version:   7.0.306
 Commit:    f500069cb7

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.22621
 OS Platform: Windows
 RID:         win10-x64
 Base Path:   C:\Program Files\dotnet\sdk\7.0.306\

Host:
  Version:      7.0.9
  Architecture: x64
  Commit:       8e9a17b221

.NET SDKs installed:
  7.0.306 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 6.0.20 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 7.0.9 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.20 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 7.0.9 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 6.0.20 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 7.0.9 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Besides the runtimes, we can see additional .NET info.

Web.Config Referencing an Incorrect DLL 

Despite the factors representing the main reasons for our error to appear, there is another not-so-common cause, a misconfigured DLL reference inside the Web.Config file.

Once our project has been compiled, a DLL file is created, usually following the convention of <ProjectName>.dll, where <ProjectName> is the name of our project. The configuration file must correctly point to the  DLL in order for the application to run correctly.

Solutions for the HTTP Error 500.31

Now that we’re familiar with the most widespread causes, let’s dive right into the fixes and solve this annoying error.

Installing the Correct Version of the .NET Core Hosting Bundle

First of all, we should be aware of the .NET Core version used by our application. For this article, we’ll be using a .NET Core 7 web application, therefore we need to install its specific .NET Core Hosting Bundle.

We can find the bundle for .NET Core 7, and for other versions, on the official Microsoft website. We can navigate here for direct download, or here where we can browse through different subversions of the 7th version.

In most cases, there are no compatibility problems between different subversions, our application should run correctly even if a different subversion of the Hosting Bundle is installed, as long as the versions are compatible.

Once the download is completed, we can go ahead and install it.

Next, restart the IIS website.

Referencing the Valid DLL in Web.Config

As mentioned before, our Web.Config file should correctly reference the compiled application  DLL. In order to verify this, let’s take a look at the root folder of our IIS website:

checking Iis-root for HTTP Error 500.31 dll file

As we can see, IisHttpError500-31.dll is the name of the DLL file, therefore let’s make sure the Web.Config invokes it correctly:

checking iis-dll-reference for the HTTP Error 500.31 path

Oops, it seems we have a typo, we’re pointing to .\IisHttpError500-31x.dll instead of .\IisHttpError500-31.dll, let’s fix it, and then, as usual, restart the IIS website.

Recycling the Application Pool

Even though the fixes above should take care of our error, sometimes it may persist because some processes or applications are crashing. This can be solved by recycling our IIS application pool, thus leading to resource cleanup. To do this we can go to the Application Pools section inside the IIS, select the pool used by our website, and recycle it:

IIS-app-pool-recycle

Conclusion

In this article, we’ve explored the HTTP Error 500.31 and enumerated some of the most common causes and how to fix them. It’s important to note that there may be additional reasons triggering this error. 

Liked it? Take a second to support Code Maze on Patreon and get the ad free reading experience!
Become a patron at Patreon!