Customize error messages on Webserve

Webserve account owners can customize error messages to provide more information about a problem or redirect website visitors to another location.

Apache configuration options

You can configure Apache to do one of four things in the event of errors:

  1. Output a simple hard-coded error message
  2. Output a customized message
  3. Redirect to a local (relative) URL to handle the error
  4. Redirect to an external URL to handle the error

The first option is the default configuration. 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 outputting the default error message, you can redirect visitors to another location, such as a problem report form.

Customize error messages

First, create 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 via a web browser (that is, world-readable).

Second, create an .htaccess file in your www directory to specify what page should display when a particular error is encountered. Replace the 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), add the ErrorDocument lines to the end of it.

UITS recommends supplying a full URL when writing the ErrorDocument directive, with the exception of the ErrorDocument 401 and ErrorDocument 404 directives, which should use the format /~username/filename. Accounts with a virtual host should use the format /filename.

For example, an account without a virtual host might use:

 ErrorDocument 401 /~username/subscription_info.html ErrorDocument 403 ErrorDocument 404 /~username/error/404.html ErrorDocument 500 

An account with a virtual host might use:

 ErrorDocument 401 /subscription_info.html ErrorDocument 403 ErrorDocument 404 /error/404.html ErrorDocument 500 
  • The URL in the 401 and 404 directive is just like a full URL, with deleted. The leading / is essential.
  • If you wish to put .htaccess in the wwws directory, you will need to create the 401 error HTML file in the wwws directory.

When you specify an ErrorDocument that points to a remote URL (that is, 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 are some of the most common error codes for which you may want to provide custom messages:

Error code Meaning
401 Unauthorized
Request did not have the proper authorization; client should supply the correct authorization when requesting this URL again
403 Forbidden
Request did 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 Found
Document at the specified URL does not exist
500 Internal Server Error
In most cases, this error results from a problem with the code or program you are calling rather than with the web server itself.

For more error codes, see Common HTML error codes.

This is document bfrb in the Knowledge Base.
Last modified on 2018-11-16 07:30:45.

Contact us

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