ASP.NET Core Hosting – 3 Simple Steps to Fix 502.5 Error in ASP.NET Core

I decide to make this tutorial as most of our users also experience same problem when deploying their ASP.NET Core application.

I recently hit this problem after manually modifying the web.config file. Fortunately, the problem is easy to fix.

In this post, we see two different causes of this error, two different solutions for the first cause, a solution for the second cause, and learn what needs to be in web.config for ASP.NET Core to operate.

The Error

Here is a screenshot of the HTTP Error 502.5 – Process Failure error. You’ll see this, in your browser, when making a request to your ASP.NET Core application, after deployment, if you have this issue.

Why do I get the error?

The HTTP Error 502.5 – Bad Gateway and HTTP Error 502.5 – Process Failure error messages occur in ASP.NET Core when IIS fails to execute the dotnet process.

I’ve seen this error happen for two different reasons:

• .NET Core Runtime is not installed
• web.config file has not been transformed

How to Fix This Error?

This is very simple and easy to fix this issue. What you need to make sure is that your hosting provider support or already installed the latest ASP.NET Core on their hosting environment. If your hosting provider doesn’t support latest ASP.NET Core, then your application will not work. You can find best ASP.NET Core hosting on our blog.

1. Install Latest .NET Core Runtime

You can download the latest .NET Core runtime from Microsoft’s .NET download page.

For Windows, you’ll usually want the latest .NET Core runtime (currently v2.1.1), as highlighted in the following screenshot:

This will get you the Windows Hosting Bundle Installer, which will install both the x86 and x64 runtimes on Windows Server.

2. Publish a Self-Contained Deployment

If you don’t want to install the .NET Core Runtime. An alternative for .NET Core web applications is to publish them in the Self-Containeddeployment mode, which includes the required .NET Runtime files alongside your application.

You can select this option from the advanced publish settings screen in Visual Studio:

If you go with this option, you’ll also need to choose a target runtime: win-x86, win-x64, osx-x64, or linux-x64. Because self-contained deployments are not portable.

3. Transform your web.config file

Another reason for this error to occur is when you deploy an untransformed web.config file.

This is likely to be your issue if you had a previously working web application and merely deployed a new version of it.

ASP.NET Core Web Config

In ASP.NET Core applications, the web.config file contains a handler that directs requests to the AspNetCoreModule and an aspNetCoreelement that defines and configures the ASP.NET Core process to execute your web application.

Here is a minimal web.config file for an ASP.NET Core application:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="%LAUNCHER_PATH%" arguments="%LAUNCHER_ARGS%" stdoutLogEnabled="true" 
        stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false"/>
  </system.webServer>
</configuration>

Note that it’s possible that you don’t have a web.config file in your ASP.NET Core project. If you do not, one will be generated for you when publishing the project, as IIS and IIS Express require a web.config file when hosting an ASP.NET Core web app.

The Issue

The untransformed web.config contains the variables %LAUNCHER_PATH% and %LAUNCHER_ARGS% rather than the correct paths. When IIS tries to run ASP.NET Core, it uses %LAUNCHER_PATH% and %LAUNCHER_ARGS% rather than the correct path and arguments.

To fix the HTTP Error 502.5 in ASP.NET Core, you need to transform the web.config and replace the untransformed web.config file on the IIS web server.

How do I transform web.config?

This transformation takes place when you choose to publish your web application. The transformed web.config ends up in the published output folder. Therefore, you simply need to publish your web application and copy the resulting web.config file onto the server.

In a transformed web.config file, the aspNetCore element will look something like this:

<aspNetCore processPath="dotnet" arguments=".\MyApplication.dll" stdoutLogEnabled="true"
stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="false" />

%LAUNCHER_PATH% has been replaced by dotnet and %LAUNCHER_ARGS% has been replaced by the path to the main web application dll .\MyApplication.dll.