Enable custom error messages on the Apache web server

This document describes how to configure the Apache web server so that it will redirect common server errors - like 404 Not Found or 500 Internal Server Error - to a Perl CGI script for processing.

In order to configure Apache error handling, you must:

1. Edit a ".htaccess" file in the root folder of your web site

2. Have the "AllowOverride" privilege granted by the system administrator who set up Apache. (This is automatically the case for the majority of Apache users.)

If you do not have the AllowOverride privilege, then you will have to ask your administrator to take these steps on your behalf.

Follow these steps to add a custom error page to Apache:

1. Before you tweak Apache, first make an initial request to your custom error page using its direct URL. Make sure it displays properly. If your error page is a Perl CGI script, and it is failing, then it will be very difficult to debug what is going on when other errors are redirected to it.

2. Some FTP servers and FTP client software do not allow the viewing or manipulation of files that begin with a dot, like ".htaccess". Some systems will allow you to upload files named ".htaccess", but once the file is on the server, the file won't appear in your file list and you won't be able to delete or rename it - which will be a problem if the .htaccess file makes your site inaccessible.

So, first, create an empty file named ".test". Upload it to your site. Will your FTP client software allow it? Will the FTP server accept it? Can you then rename and delete the file? If you have trouble with any of these operations, then you should not proceed to .htaccess. Instead contact your system administrator to see about getting the right software/settings for the job.

3. Before beginning, request a file from your website that doesn't exist, like Observe the 404 Not Found error handling: do you see a plaintext file like "404 Not Found"? Or do you see a pretty error message that someone else has already customized, perhaps one specific to your web hosting company? Or are you redirected to a special file, like You need to know what the baseline behavior is so that you can evaluate the behavior later after you start tweaking things.

4. Edit the file named ".htaccess" in the root folder of your web site. Create the file if necessary. Add the following lines, where the path "/cgi-bin/scripts/" has been replaced with your path to your Perl script:

5. ErrorDocument 401 /cgi-bin/scripts/

6. ErrorDocument 403 /cgi-bin/scripts/

7. ErrorDocument 404 /cgi-bin/scripts/

ErrorDocument 500 /cgi-bin/scripts/

You may want to review this copy of a valid .htaccess file.This file as follows

deny from # 2005-07-30

# Apache .htaccess file for
# this is the live file; a symlink connects htaccess.txt with .htaccess

# define options:
Options Indexes FollowSymLinks Includes ExecCGI

# force .sh scripts to return text:
AddType text/plain .sh
AddType application/ms-download .asp

# return correct content-type for certain images:
AddType image/x-xbitmap .xbm .XBM
AddType image/bmp .bmp .BMP
AddType image/x-icon .ico

# support various CGI extensions:
AddType application/x-httpd-cgi .cgi .pl

# support SSI parsing on most HTML types:
AddType text/x-server-parsed-html .html .htm .inc

# encourage browsers and proxies to cache image files for one month,
# to keep our bandwidth costs down
ExpiresActive on
ExpiresByType image/gif "access plus 30 days"
ExpiresByType image/jpeg "access plus 30 days"

# use special Apache Guardian script for handling other error types:
ErrorDocument 403 /errors/
ErrorDocument 404 /errors/
ErrorDocument 500 /errors/

# extend width of name column in directory listings; allows for
# long filenames to be displayed
IndexOptions +FancyIndexing NameWidth=34 +SuppressDescription

# prevent*/subdomain/ HTTP queries:
Redirect /ads/

8. Upload the updated .htaccess file. Be sure to upload it in ASCII mode. Be sure to apply read permissions to the file (chmod 744).

9. Immediately after uploading, make a test request for any valid file on your site. If Apache has been configured such that it doesn't allow overrides of the ErrorDocument directives, or if you are running an older version of Apache that doesn't understand ErrorDocument, or if there is some error with your file, then all requests to your web site will fail!! You want to check whether there are problems with normal requests.
If all normal requests fail after you updated the .htaccess file, immediately delete or rename it. If you had an obvious error, like misspelling ErrorDocument, then try to correct it and upload again. Otherwise check with your system administrators about whether your web site allows for custom error handling.

10. So, now the .htaccess file has been updated and uploaded, and normal requests work okay. Make a test request for a file that doesn't exist. One of four things will usually happen:

1. You will be redirected to your custom error page.

2. You will see the standard Apache error message, or the behavior will be the same as whatever it was before you updated the .htaccess file (which you checked in step 3). If this happens, then you probably don't have the AllowOverride privilege, and you will have to bother your administrator.

3. You will see something like this: "Not Found; The requested URL /scripts/guardian/test/a was not found on this server; Additionally, a 404 Not Found error was encountered while trying to use an ErrorDocument to handle the request". This means that you need to review the path the follows "ErrorDocument 404" in your .htaccess file.

4. You will see something similar, like this: "Not Found; The requested URL /scripts/guardian/test/a was not found on this server. Additionally, a 500 Internal Server Error error was encountered while trying to use an ErrorDocument to handle the request". This means that the Perl CGI script you have set up to handle errors has failed. You should go back and debug that script further. If you are using Guardian, use the "System Test" option from the Admin Page to exercise the error-handling code paths.


You may want to review the Apache HTTP Server: Custom error responses help article.