Share via

When AspNetCoreModuleV2 is missing in IIS (e.g., Hosting Bundle not installed), IIS and "appcmd" only report a vague “Configuration error” with no details. This makes root cause analysis extremely difficult in production.

RAVIRAJ DESAI 0 Reputation points
2025-09-13T15:13:04.2133333+00:00

Summary

When AspNetCoreModuleV2 is missing in IIS (e.g., Hosting Bundle not installed), IIS and "appcmd" only report a vague “Configuration error” with no details. This makes root cause analysis extremely difficult in production. A clearer error pointing to the missing Hosting Bundle would greatly improve diagnostics.

Description

Problem When deploying an ASP.NET Core 8 app to IIS, if the server does not have the ASP.NET Core Hosting Bundle installed (so AspNetCoreModuleV2 is missing), the site’s web.config with element causes IIS to throw a generic error.

For example, running: %windir%\system32\inetsrv\appcmd list config "Default Web Site/MyApp" returns only: ERROR (message: Configuration error Filename: D:...\web.config Line Number: 0 Description: )

This gives no actionable information. It does not indicate that the aspNetCore handler is unrecognized or that the Hosting Bundle is missing.

#area-IIS#Enhancement#aspnetcore#deployment

Describe the solution you'd like

IIS / ANCM should report a clearer error, such as: Unrecognized configuration section 'system.webServer/aspNetCore'. Ensure the ASP.NET Core Hosting Bundle is installed and AspNetCoreModuleV2 is available.

Additional context

Reproduction Steps

1. On a clean Windows Server (2019/2022) with IIS installed but without the .NET Hosting Bundle: Add-WindowsFeature Web-Server, Web-Asp-Net45

2. Create a new IIS site (e.g. MyApp) and add this web.config to its root folder:

3. Run %windir%\system32\inetsrv\appcmd list config "Default Web Site/MyApp"

4. Observe the output: ERROR (message: Configuration error Filename: D:...\web.config Line Number: 0 Description: )

Expected Result

A clear error message that indicates the aspNetCore section is not recognized because AspNetCoreModuleV2 is missing. Example: Unrecognized configuration section 'system.webServer/aspNetCore'. Ensure the ASP.NET Core Hosting Bundle is installed.

Real-World Impact

  1. In our production environment, the Hosting Bundle was not properly registered, and the AspNetCoreModuleV2 handler was missing.
  2. The IIS Manager GUI showed only a generic “configuration error” with no details.
  3. Running appcmd list config gave the unhelpful output shown above (empty description).
  4. This made it extremely difficult to diagnose. We had to spend hours checking configs, comparing UAT vs PROD, and even reinstalling IIS features before finally discovering the root cause.
  5. A clearer message pointing directly to the missing Hosting Bundle would have saved several hours of downtime and troubleshooting in a production-critical environment.
Developer technologies | .NET | .NET Runtime
0 comments

3 answers

Sort by: Most helpful
Most helpful Newest Oldest
  1. Bruce (SqlWork.com) 81,191 Reputation points Volunteer Moderator
    2025-09-15T15:44:35.28+00:00

    until the core module or any similar module is installed and adds its new configuration values, IIS does not know the additional syntax added to config files. its just an unknown config value.

    0 comments
  2. Danny Nguyen (WICLOUD CORPORATION) 3,500 Reputation points Microsoft External Staff
    2025-09-16T06:29:18.3733333+00:00

    Hi @RAVIRAJ DESAI ,

    Thanks for sharing this detailed report — I understand how frustrating it is to see only a vague “Configuration error” when the Hosting Bundle (and AspNetCoreModuleV2) is missing. In production, that lack of clarity definitely makes diagnosis harder.

    What’s happening under the covers:

    • IIS only knows about configuration schema that is registered by installed modules.
    • Until AspNetCoreModuleV2 (part of the Hosting Bundle) is installed, IIS doesn’t recognize <aspNetCore> as valid config.
    • As a result, it treats it as an unknown section and surfaces the generic error you saw, instead of a specific “Hosting Bundle not installed” message.

    So technically this is expected — IIS itself has no awareness of the ASP.NET Core module until it’s registered. That’s why you’re seeing the vague output.

    That said, I appreciate the time you put into documenting this scenario and opening an issue on ASP.NET Core GitHub repository. A clearer error message would definitely help administrators save time during troubleshooting, and I hope your feedback will lead to improvements in future releases.

    0 comments
  3. Surya Amrutha Vaishnavi Lanka (INFOSYS LIMITED) 810 Reputation points Microsoft External Staff
    2025-09-16T06:56:04.95+00:00

    Thanks for sharing the details, this usually happens if the .NET Core Hosting Bundle is not installed on the server. IIS then throws a vague "Configuration error" without pointing out the real cause.

    some steps u can follow to fix it

    1. Download the latest .NET Core Hosting Bundle from Microsoft official site.
    2. Install it on the server.
    3. Restart IIS using, iisreset
    4. Verify that the module AspNetCoreModuleV2 is available in IIS.

    Without the Hosting Bundle, IIS will only show a generic “Configuration error” and won’t give details. Installing the Hosting Bundle resolves this and allows the ASP.NET Core app to run correctly.

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.