Create customized error messages for your web page

This information is applicable primarily to Unix systems running the Apache World Wide Web server, which runs on Pages and Webserve at Indiana University.

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.

Create customized error messages

The easiest way to customize the error messages for your site is to use .htaccess files. With .htaccess files, you can make your web server substitute pages of your choice for the generic error messages it normally displays. You may designate different files for each error message, and with multiple .htaccess files, you may also create a set of messages for each part of your site.

Follow these instructions to customize your error messages:

  1. Create web pages for each of your customized error messages. It doesn't really matter where you put them, but make sure they are accessible to a web browser.
  2. Open the .htaccess file in a text editor like Emacs, vi, or Pico. You must pay more attention to where you place this file. The server will consult the .htaccess file every time it tries to access a page from the directory it's in, as well as any subdirectories. If you put another .htaccess file in a subdirectory, it will override .htaccess files in parent directories.
  3. The syntax for the .htaccess file is as follows:
     ErrorDocument ErrorCode Address
    Replace ErrorCode with the error number of the standard error message you want to replace (for example, 401, 403, 404, 500) and Address with the URL of the file you want as the replacement message, for example:
     ErrorDocument 403 ErrorDocument 404

    HTML error codes have the following meanings:

    Unauthorized. This indicates a password error, for example.
    Forbidden. The file exists, but isn't world readable.
    Unknown. The file doesn't exist at the location specified.
    500 Internal server error.

    If you already have an .htaccess file (to password-protect a directory, for example), just add the ErrorDocument lines to the end of it.

    On Webserve, for ErrorDocument 401 and ErrorDocument 404, you should not use a full URL and instead should use the format /~username/filename. Accounts with a virtual host should use the format /filename.
  4. Once you have finished, exit your editor and set the protections of the .htaccess file with the following command:
     chmod 644 .htaccess

At Indiana University, for personal or departmental Linux or Unix systems support, see Get help for Linux or Unix at IU.

This is document agxp in the Knowledge Base.
Last modified on 2018-10-30 12:51:17.

Contact us

For help or to comment, email the UITS Support Center.