Error Documents

Apache gives you the ability to use custom error strings or documents. This can be configured for different types of errors, and you can specify either a file or a script to process the error.

Catching Errors

The .htaccess file is used to enable error documents, using the ErrorDocument command. This command takes two arguments, an error code, and a URL which should process the error.

As an example, the .htaccess file used by this directory contains:

ErrorDocument 401 /webinfo/error/auth_required.html
ErrorDocument 403 /webinfo/error/forbidden.cgi
ErrorDocument 404 /webinfo/error/not_found.cgi
ErrorDocument 500 /webinfo/error/server_error.cgi

Note: If you are working in wwwdev, wwwudev, or the production directories for www.washington.edu, you need to have the ErrorDocument entries in a .htaccess file in each tree you use. For example, if you use the world and uw trees, you need to have a .htaccess file with these ErrorDocument lines in each tree.

Also, if you do not already have a directory in the world tree, you must have one made and put a copy of the .htaccess file there, or the File Not Found error document will not be used.

Common Error Codes

The error codes used above are the most common ones. Their definitions are:

401

Authorization required. Usually given because a username/password combination was not provided.

403

Access denied. Some reasons are because the username/password suplied wasn't permitted access, or the user is trying to access a directory that has neither an index.html (or index.htm or index.cgi) file nor directory indexing enabled.

404

Not found. The URL entered (or linked to) isn't on the system.

500

Server error. Usually because a CGI script has exited with an abnormal exit code.

CGI Interface

If you choose to supply an error CGI script, the usual CGI variables are available for use, but they have the REDIRECT_ string prepended to them. For example, the usual variable REMOTE_HOST will instead be named REDIRECT_REMOTE_HOST. You're always guaranteed to have the REDIRECT_URL (URL which generated the error) and REDIRECT_QUERY_STRING (arguments after the ? in the URL) variables.

If the server registered a string explaining the reason for the error, that string is available as REDIRECT_ERROR_NOTES.

Examples

Here are examples of the error documents defined by the .htaccess file above.

Authorization Required - One way of handling an invalid username/password pair is to offer the user the chance to register so they can gain access to the pages which are protected. This is an example of that. Be sure to cancel the dialog box so you can see the error document. You can also view the source to this document.

Access Denied - This script will detect whether you are trying to do a directory listing (as in this case) or trying to access a file which can't be read (or your username/password doesn't have access to). You can view the source to this perl script.

File Not Found - This is a shell script which will tell a user that a file they are looking for isn't there. If the user came via a link and that information has been passed to us, the script will note that, too. You can also view the source to the script.

Server Error - This link points to a CGI which returns an error, triggering the Server Error. You can view the source to this error script.