In-depth Analysis and Practical Guide to Resolving HTTP Error 502.5 for ASP.NET Core Sites in IIS

Problem Background and Symptom Analysis

In a Windows Server 2012 R2 environment, an ASP.NET Core website that previously functioned correctly suddenly becomes inaccessible via IIS after an update deployment, with browsers returning HTTP Error 502.5 (Process Failure). The error message indicates "Process Failure" and includes a Microsoft support link. Interestingly, when running the executable (.exe) directly from the publish directory on the server, the website works fine on a local port (e.g., 5000), suggesting the issue is not with the application itself but rather with the IIS hosting process.

Examining the Windows Event Viewer reveals a critical error: Application 'MACHINE/WEBROOT/APPHOST/DEFAULT WEB SITE/MySite' with physical root 'D:\Sites\MySite\' failed to start process with commandline '"%LAUNCHER_PATH%" %LAUNCHER_ARGS%', ErrorCode = '0x80070002 : 0. Error code 0x80070002 typically means the system cannot find the specified file, directly pointing to a process startup path configuration issue.

Despite attempts to reinstall the .NET Core Hosting Bundle, the error persists. Enabling stdout logging generates log files, but they remain empty (0KB), further indicating that the process failed to start and could not output any runtime information.

Core Issue: web.config Misconfiguration

According to the best answer analysis, the root cause lies in the aspNetCore section of the web.config file using an invalid processPath value. %LAUNCHER_PATH% is an undefined environment variable that does not exist on the system, preventing IIS from resolving and launching the corresponding process. The correct configuration should directly specify the relative or absolute path to the executable file.

Incorrect configuration example:

<aspNetCore requestTimeout="02:00:00" 
     processPath="%LAUNCHER_PATH%" 
     arguments="%LAUNCHER_ARGS%" 
     stdoutLogEnabled="true" 
     stdoutLogFile=".\logs\stdout" 
     forwardWindowsAuthToken="false" />

Corrected configuration example:

<aspNetCore requestTimeout="02:00:00" 
     processPath=".\yourAppName.exe" 
     arguments="" 
     stdoutLogEnabled="true" 
     stdoutLogFile=".\logs\stdout" 
     forwardWindowsAuthToken="false" />

Here, processPath is set to yourAppName.exe in the current directory (adjusted based on the actual application name), and arguments can be left empty or specified as needed. This configuration ensures IIS can accurately locate and start the application process.

It is crucial to note that when running the executable directly from the command line, the web.config file is completely ignored, thus avoiding this error. This explains why the application works normally when executed directly but fails under IIS hosting. This mechanism difference is key to understanding the issue: IIS relies on web.config to configure hosting behavior, while command-line execution bypasses this configuration.

Supplementary Solutions and Diagnostic Techniques

Beyond fixing processPath, other answers provide valuable supplementary insights. For instance, if the application depends on the .NET Core runtime, it may be necessary to explicitly specify the path to dotnet.exe, especially if system environment variables are not set correctly. A corrected configuration is as follows:

<aspNetCore processPath="C:\Program Files\dotnet\dotnet.exe" arguments=".\your-project.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout"/>

Here, processPath points to the full path of dotnet.exe, and arguments specifies the DLL file to run. This is suitable for applications launched using the dotnet command, ensuring IIS can correctly invoke the .NET Core runtime.

Another common issue is errors in application configuration files, such as appsettings.json. For example, invalid escape sequences or formatting problems can cause process startup failures. An effective diagnostic method is to open a command prompt on the server, navigate to the application directory, and run dotnet yourSite.dll (replace yourSite.dll with the actual main DLL filename). If configuration errors exist, the command line will immediately output detailed error information, helping to quickly identify the source of the problem. This is more efficient than relying on blank stdout logs.

Practical Steps and Preventive Measures

To systematically resolve HTTP Error 502.5, it is recommended to follow these steps:

1. Check web.config Configuration: First, verify that the processPath and arguments values in the aspNetCore section are correct. Ensure the paths exist and are accessible, avoiding undefined environment variables like %LAUNCHER_PATH%.
2. Enable and Analyze Logs: Set stdoutLogEnabled="true" and specify a log file path. If log files are empty, it typically indicates the process failed to start, and focus should be on checking configurations and dependencies.
3. Command-Line Testing: Run dotnet yourSite.dll or directly execute the .exe file in the application directory to observe any error outputs. This helps distinguish between IIS configuration issues and internal application errors.
4. Verify Dependencies: Ensure the server has the correct version of the .NET Core Hosting Bundle installed and that the IIS application pool configuration matches the application requirements (e.g., setting .NET CLR version to "No Managed Code").
5. Regularly Review Deployment Processes: During update deployments, automate checks for web.config file integrity to prevent configuration drift from manual changes. Use configuration templates or tools (such as ASP.NET Core publish profiles) to maintain consistency.

By applying these methods, developers can not only quickly resolve current 502.5 errors but also establish preventive mechanisms to reduce similar issues in future deployments. Understanding the differences between IIS hosting and direct execution is key to ensuring the stable operation of ASP.NET Core applications.