Click to return to the Server Technologies home page    
Web Workshop  |  Server Technologies

Custom Error Messages with Internet Information Server 4.0

Microsoft Corporation

August 21, 1998

Editor's note: The following is from our help documentation for Internet Information Server (IIS) 4.0. This help topic can be brought up on any machine with IIS 4.0 installed. Just type http://localhost/iishelp and search for "custom errors" from the Windows NT® 4.0 Option Pack Search panel.

Custom Error Messages

IIS 4.0 enables administrators to customize the content that is displayed to the client in the case of HTTP errors (such as "404 Not Found"). Instead of using the HTTP 1.1 error messages that are returned to the client by default, Web site administrators can choose to send the client other error messages. These customizable error messages can be in the form of a file or a URL.

If you have an ASP script defined to handle a custom error, the script is invoked as a URL which passes context. That is, the type of error is passed along in the URL to the page you have defined to handle that type of error. For example, if you have an ASP file called handle404.asp that is defined to handle HTTP 404 errors, when a user tries to access example.htm and a 404 error occurs, the ASP file will be invoked as if the user had typed

http://example.microsoft.com/handle404.asp?404;http://example.microsoft.com/example.htm

in the Web browser.

Note Custom error messages appear as a list in Internet Service Manager and this list is treated as a single property by IIS. When a set of custom errors is configured at the Web site level, all directories under that server inherit the entire list of custom error messages. That is, the two custom error message lists (for server and directory) are not merged.

If you are using static custom error files (HTML files), you should always use the File option. If you plan on developing an application (via ISAPI or ASP) to handle errors, use the URL option, but be aware that the error status is handed to the application in the URL parameters and it is the application's responsibility to set the HTTP header status, otherwise the HTTP response status will be HTTP 1.1 200 OK.

The following HTTP error messages can be customized:

Note Error codes 401 and 403 have sub-codes, which allow for more flexibility in customizing the messages.

"400"; Bad Request

"401"; Unauthorized

  1- Logon failed

  2- Logon failed due to server configuration

  3- Unauthorized due to ACL on resource

  4- Authorization failed by filter

  5- Authorization failed by ISAPI/CGI application

"403"; Forbidden

  1- Execute access forbidden

  2- Read access forbidden

  3- Write access forbidden

  4- SSL required

  5- SSL128 required

  6- IP address rejected

  7- Client certificate required

  8- Site access denied

  9- Too many users

  10 - Invalid configuration

  11 - Password Change

  12 - Mapper Denied Access

"404"; Not Found

"405"; Method Not Allowed

"406"; Not Acceptable

"407"; Proxy Authentication Required

"412"; Precondition Failed

"414"; Request-URL Too Long

"415"; Unsupported Media Type

"500"; Internal Server Error

"501"; Not Implemented

"502"; Bad Gateway

Adding a Custom Error Message

Custom errors may be implemented by mapping to a file or a mapping to a URL. Both of these procedures can be achieved by using the Custom Errors property sheet in Internet Service Manager. The following procedure explains how to customize an HTTP error by mapping the error to a URL.

To customize an error message by mapping to a URL:

  1. Create a file that contains your custom error message and place it in a virtual directory.
  2. In Internet Service Manger, select the Web site, virtual directory, directory, or file in which you would like to customize HTTP errors and click the Properties button.
  3. Select the Custom Errors property sheet.
  4. Select the default HTTP error that you would like to change.
  5. Click the Edit Properties button.
  6. Select URL from the Message Type box
  7. Type the URL that points to your customized error message.
  8. Click OK.

Friendly Custom Error Messages

IIS features its own set of custom errors that provide more informative or "friendly" feedback than the default HTTP 1.1 errors that are returned to client browsers. For example, the HTTP 1.1 404 error message, which by default simply reads "Object Not Found" is expanded to read "The web server cannot find the file/script you asked for. Please check the URL to ensure that the path is correct. Please contact the server's administrator if this problem persists." These friendly custom error messages are set by default in the Default Web Site in Internet Service Manager.

To configure friendly error messages:

  1. In Internet Service Manger, select the Web site, virtual directory, directory, or file in which you would like to customize HTTP errors and click the Properties button.
  2. Select the Custom Errors property sheet.
  3. Select the default HTTP error that you would like to change.
  4. Click the Edit Properties button.
  5. Select URL from the Message Type box.
  6. Type /iisHelp/common/<file name> where <file name> is the HTML file name of the friendly error message.

Friendly error messages are installed by default to the following location: <drive letter>:\WINNT\Help\common. The file names are numbers which correspond to the specific HTTP errors; for example, 400.htm, 401-1.htm, and so on.



Back to topBack to top

Did you find this material useful? Gripes? Compliments? Suggestions for other articles? Write us!

© 1999 Microsoft Corporation. All rights reserved. Terms of use.