Skip to main content

How to Troubleshoot an IIS 500.21 Handler Error

An IIS 500.21 error indicates that the web server is unable to call the specific handler required to process the request. This typically occurs on Windows Server when the underlying application module (such as ASP.NET or the .NET Core Hosting Bundle)...

An IIS 500.21 error indicates that the web server is unable to call the specific handler required to process the request. This typically occurs on Windows Server when the underlying application module (such as ASP.NET or the .NET Core Hosting Bundle) is not correctly registered or installed.

Before you begin

You will need:

  • Administrator access to the Windows Server

  • Access to the Internet Information Services (IIS) Manager console

  • The specific error message or request path that triggers the 500.21 error

Check the handler registration

The most common cause of a 500.21 error is a missing or incorrectly configured handler mapping in IIS.

  1. Open Internet Information Services (IIS) Manager.

  2. In the Connections pane, select the server or the specific website.

  3. Double-click Handler Mappings in the center pane.

  4. Locate the handler associated with the technology you are using (e.g., aspNet_1.0 or aspNet_4.0).

  5. Verify that the handler exists and is assigned to the correct request types.

Verify the application runtime installation

If the handler is missing from the list or does not appear to be functioning, the required runtime components may not be installed on the server.

For ASP.NET applications

  1. Open Control Panel > Programs and Features.

  2. Check for the presence of the Microsoft .NET Framework (e.g., 4.x) and the ASP.NET features.

  3. If missing, install the appropriate .NET Framework version.

For ASP.NET Core applications

  1. Open Control Panel > Programs and Features.

  2. Verify that the Microsoft .NET Core Hosting Bundle is installed.

  3. If the bundle is not present, download and install the version that matches your application's target framework.

Restart the IIS service

After installing new components or modifying handler mappings, you must restart the web server to apply the changes.

  1. Open the Command Prompt as an Administrator.

  2. Type iisreset and press Enter.

  3. Wait for the service to restart.

Confirm the result

  • The website should now load successfully at the requested URL.

  • The 500.21 error page should no longer appear in the browser.

Troubleshooting a web.config Configuration Error

If the error persists and the browser displays a "web.config Configuration Error" message instead of a 500.21 error, the issue may be a syntax error or an invalid configuration within your application's local configuration file.

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

  2. Check for any red-highlighted lines or malformed XML tags.

  3. Ensure that any custom modules or handlers defined in the <system.webServer> section are correctly formatted.

  4. Save the file and refresh the browser.

Did this answer your question?