Indiana University

IU Webmaster

Custom Error Messages

Account owners on Webserve can customize error messages to provide more information about a problem or redirect web site visitors to another location.

Background Information

Apache can be configured to do one of four things in the event of errors:

  1. output a simple hardcoded error message
  2. output a customized message
  3. redirect to a local (relative) URL to handle the problem/error
  4. redirect to an external URL to handle the problem/error

The default configuration is to output a simple hardcoded error message (Option #1). Options 2-4 are configured within the .htaccess file.

The Apache web server software used on Webserve contains an "ErrorDocument directive" which allows you to control the error response that visitors to your site will see. Instead of the default error message, you can redirect visitors to another location, such as a problem report form.

How to customize error messages

First, create an HTML files (web pages) for each of your custom error messages. These error pages may be located anywhere within your www directory structure and must be accessible to a Web browser (i.e. world-readable).

Second, create an .htaccess file in your www directory to specify what page should be displayed when a particular error is encountered. Replace username and the file name with your username and file name. If you already have an .htaccess file (to password protect a directory, for example) just add the ErrorDocument lines to the end of it.

We recommend supplying a full URL when writing the ErrorDocument directive. However, for the ErrorDocument 401, /~username/filename format should be used. Otherwise, every page delivered results in error messages in the log file, even though there is no 401 error. 

ErrorDocument 401 /~username/subscription_info.html
ErrorDocument 403 http://www.indiana.edu/~username/forbidden.html 
ErrorDocument 404 http://www.iupui.edu/~username/cgi-bin/bad_urls.pl
ErrorDocument 500 http://foo.example.com/cgi-bin/tester

Note:

  1. The URL in the 401 directive is just like a full URL with this part, "http://www.indiana.edu" deleted. The leading / is essential.
  2. If you wish to put .htaccess in the wwws directory, then you need to create the 401 error html file in the wwws directory.

When you specify an ErrorDocument that points to a remote URL (i.e., anything with a method such as "http" or "https" in front of it) Apache will send a redirect to the client to tell it where to find the document, even if the document is really located on the same server. This is a result of the nature of the HTTP basic authentication scheme.

If you want to provide different error messages for various areas of your site, you can put a different, customized .htaccess file into any subdirectory.

Here's a list of some of the most common error codes for which you may want to provide custom messages:

Error CodeMeaning
401 UnauthorizedRequest did not have the proper authorization. Client should supply the correct authorization when requesting this URL again.
403 Forbidden The request does not specify the file name. Or the directory or the file does not have the permission that allows the pages to be viewed from the web.
404 Not FoundThe document at the specified URL does not exist.
500 Internal Server Error In most cases, this error is a result of a problem with the code or program you are calling rather than with the web server itself.

Knowledge Base also has a document on this topic.