Enable custom errors in WordPress on IIS 7.0

The information in this post is not applicable anymore because the update that fixes the custom errors problem in IIS 7.0 FastCGI module has been made available . Read the release announcement to get more details about the update.

Recently, I found out that my WordPress powered blog did not correctly handle 404 – File Not Found errors. When a request was made to a non-existent page, then instead of getting nice WordPress based error page, visitors used to get a generic IIS 7.0 404 error page. Somehow, I have missed that part of the configuration when I set up WordPress initially. The fix for that turned out to be very simple, but since it seems to be a very common configuration task when hosting WordPress on IIS 7.0, I decided to explain the necessary configuration steps.

By default IIS is configured to return detailed error messages for local requests and custom error messages for remote requests. So when request is made to http://ruslany.net/boguspage, the server returns this:

This is a custom IIS error page. Typically, this is not the kind of response you would want your blog visitors to see. Instead, it would be nice to return an error page generated by WordPress. Almost all WordPress themes have a template for the 404 error called 404.php. This template tells WordPress how to generate an error page, that should be returned when URL is not found on the server. To return that page instead of the generic IIS page do the following:

  1. In IIS Manager open the “Error Pages” feature UI for your web site
  2. Select the status code 404 from the list view and click “Edit” action
  3. In the “Edit Custom Error Page’ dialog choose an option “Execute a URL on this site”
  4. Enter the URL as “/index.php?error=404

Here is how the IIS Manager UI will look like:

Alternatively, you can add the following configuration section into the <system.webServer> section of web.config file located at the root folder of your web site:

  <remove statusCode="404" subStatusCode="-1" />
  <error statusCode="404" prefixLanguageFilePath=""
responseMode="ExecuteURL" />

Note, that by default the IIS “Error Pages” feature is not delegated for being configured via web.config file. This means that if you use shared hosting, you can add <httpErrors> section to web.config file only if hosting provider has delegated the “Error Pages” feature.

Once the configuration change has been made, any request to a non-existent URL will result in the standard WordPress error response:


ruslany on December 5th 2008 in PHP, WordPress

PoorFairAverageGoodExcellent (No Ratings Yet)

9 Responses to “Enable custom errors in WordPress on IIS 7.0”

  1. Gravatar Imagenaokiharu responded on 06 Jan 2009 at 8:17 am #

    Would you also tell me know how to configure the same thing on IIS6.0? I’m using WHS + IIS 6.0 + FastCGI + PHP 5x.

  2. Gravatar Imageruslany responded on 08 Jan 2009 at 4:50 pm #

    On IIS 6.0 follow these steps:

    1. In the IIS manger tree view choose the web site where WordPress is installed;
    2. Right click and select “Properties”;
    3. In the dialog choose the “Custom Errors” tab;
    4. In the list of the errors find the 404 error and double click on it;
    5. In the “Edit Custom Errors Properties” dialog, choose message type as URL and enter URL as /index.php?error=404

  3. Gravatar ImageAlan responded on 31 Jul 2009 at 4:10 am #

    Thank you!

    This is the stuff that works! Thank you, thank you, thank you!


  4. Gravatar Imageruslany responded on 12 Aug 2009 at 4:13 pm #

    This blog post explains a better way of enabling custom errors on IIS 7.

  5. Gravatar Imagekjcristiano responded on 28 Aug 2009 at 1:36 pm #

    I see you have now linked to the blog post about using Passthrough Error messages for IIS 7 and wordpress.

    Have you tested this out?

    I know with wp_die it will through IIS a 500 error if a comment does not have all the required fields which returns an Internal Servber Error on IIS7, but the custom text on apache. So the passthrough will solve this issue, but what if there is no custom message from the App?

    I have started to test this out (and so far it works fine), but before I implement on my blogs I’d love to know how others have fared with this.



  6. Gravatar Imageruslany responded on 28 Aug 2009 at 1:42 pm #

    @kjcristiano: I have been using the Passthrough approach now on my blog for couple of months not and it seems to work fine so far. If there is not custom messager from the app, then IIS should use the default custom error.

  7. Gravatar ImageAlex responded on 09 Jun 2010 at 8:12 am #

    This post really helped thanks – just what I needed to get my custom 404 to start displaying :-)



  8. Gravatar ImageLars Nielsen responded on 11 Nov 2011 at 6:44 am #

    Thanks for this post – saved me a load of time trying to figure out what was going on. For those using Instant WordPress to develop WordPress sites on their own machine, note that Instant WordPress uses Apache even on a Windows machine. So the 404 will work OK on your developer machine but when you deploy it to a live IIS based server, you need to make the changes described here.

  9. Gravatar ImageLee responded on 13 Mar 2012 at 10:32 pm #

    It is also useful for config the web.config file in IIS Express.Thank you very much.I am install the WordPress using the WebMatrix.

Trackback URI | Comments RSS

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

XML Markup: If You want to add XML code to the comment please XML encode it first, otherwise the code will not show up.

Recently Published Articles