Skip to main content

How to Troubleshoot a web.config Configuration Error

A web.config configuration error prevents an IIS website from loading, typically resulting in a 500.19 or 500.21 HTTP error. This guide helps a Windows Server administrator identify and resolve syntax or configuration issues within the web.config file...

A web.config configuration error prevents an IIS website from loading, typically resulting in a 500.19 or 500.21 HTTP error. This guide helps a Windows Server administrator identify and resolve syntax or configuration issues within the web.config file for a specific IIS website.

Before you begin

You will need:

  • Administrator access to the Windows Server.

  • Access to the IIS Manager console.

  • The specific URL or site name experiencing the error.

Check the specific IIS error code

The type of error you see in a browser or the IIS logs indicates where the configuration is failing.

Identifying a 500.19 error

A 500.19 error indicates that the web.config file contains elements that are not allowed by the current IIS configuration. This often happens when a feature (like the .NET Core Hosting Bundle) is missing or when a section is locked at the server level.

  1. Open the IIS Manager.

  2. Select the site and attempt to load it in a browser.

  3. If the error is 500.19, the issue is likely a missing module or an invalid configuration section.

Identifying a 500.21 error

A 500.21 error indicates that the web.config file is valid, but the specific handler or module requested is not installed or enabled on the server.

  1. Check the error code in the browser or the IIS logs.

  2. If the error is 500.21, the issue is a missing handler or module.

Identifying a general 500.00 error

A generic 500.00 error often points to a malformed XML structure in the web.config file.

  1. Open the web.config file in a text editor (such as Notepad++).

  2. Check for unclosed tags, incorrect nesting, or special characters.

Verify the web.config file syntax

If the error is a general 500.00 or a "Configuration Error" message, the XML may be malformed.

  1. Open the web.config file located in the website's root directory.

  2. Check for:

    • Missing closing tags (e.g., <system.webServer> without a closing </system.webServer>).

    • Duplicate sections (e.g., two <modules> tags).

    • Special characters or symbols that are not valid in XML.

  3. Save the file and refresh the website.

Verify required modules and features

If you receive a 500.19 or 500.21 error, the web.config is trying to use a feature that IIS does not recognize.

  1. Identify the specific section causing the failure (often listed in the detailed error page).

  2. If the error involves AspNetCore, ensure the ASP.NET Core Hosting Bundle is installed.

  3. If the error involves a specific module (like Rewrite), ensure the URL Rewrite Module is installed.

  4. If the error states a section is "locked," you may need to unlock that section in the IIS configuration.

Check the IIS logs for specific details

When the browser provides a generic error, the IIS logs can provide more specific information about the failure.

  1. Open IIS Manager.

  2. Select the site and click Basic Settings to confirm the path.

  3. Navigate to the site's log folder (typically C:\inetpub\logs\LogFiles\W3SVC1\).

  4. Open the most recent log file.

  5. Look for the entry corresponding to your request. The status code and sub-status code will provide more detail on the failure.

Confirm the result

  • The website loads successfully without a 500-series error.

  • The web.config file is successfully parsed by IIS.

Troubleshooting common configuration issues

The "Section is Locked" error

If you receive an error stating that a section is "locked" or "not allowed," it means the web.config is trying to override a setting that is restricted at the global IIS level.

  1. Open the IIS Manager.

  2. Select the Server Name in the left pane.

  3. Open Configuration Editor.

  4. Navigate to the section mentioned in the error (e.g., system.webServer/modules).

  5. Ensure the section is enabled and not restricted by a feature delegation.

Missing ASP.NET Core Hosting Bundle

If your web.config contains <aspNetCore> elements and you receive a 500.19 error, the Hosting Bundle is likely missing.

  1. Verify the version of the ASP.NET Core Hosting Bundle installed on the server.

  2. If it is missing or the wrong version is installed, download and install the version matching your application's .NET runtime.

  3. Restart the World Wide Web Publishing Service (IIS) after installation.

Limitations

  • This procedure does not resolve issues caused by incorrect file permissions on the web.config file.

  • This procedure does not address errors caused by incorrect database connection strings within the web.config.

  • Changes to the web.config file are immediate and do not require an IIS restart unless a new module is installed.

Did this answer your question?