http_errors.cgi is a simple Perl script that handles HTTP errors with a little more style than the server tends to. It does some things that Apache's mod_speling and mod_rewrite can do if so configured. The latest version of this script can always be found at <URL:>

You can RTFM on Apache at <URL:>

Use a simple text editor, such as notepad, to create and configure these files. If you have trouble getting http_errors to run, or are new to CGI and Perl, see my Webhelp: Perl (online).

This script was developed on Apache in Win32. It runs on my site with Apache on Linux. Whether or not in runs correctly on other configurations I have no idea; a note on your success or failure would be appreciated though.


What does it do?

It handles 404 and 403 HTTP errors. Well so does the server, so what? Okay, it does a little more. And if you know Perl I encourage you to make your own additions, I have several extra functions in the script catching errors at I had to simplify the thing to post it here since most of the additions are specific to my site. Of course you don't want to get too carried away; i.e. if you want a different error page for each directory then put a .htaccess file in each directory and point to a page or script to use. Perhaps I'll get around to making a HTML interface to aid in further configuration of http_errors.cgi. Your ideas for modifications are welcome.

  1. Changes the requested URL to all lowercase and checks to see if a file by that name is available. (I use all lowercase so this makes sense to me.) If its available the user is sent there.
  2. Does any specific URL rewriting that you want to do. There's an example in the script. If you need to do alot of this you should see about mod_rewrite and/or mod_speling, if you use Apache at any rate.
  3. Renders a HTML error page with helpful hints, a search link, or whatever else you care to put on it (message.txt). A special message is given to Error 404s occurring in the /temp/ directory stating that these are temporary files. If you don't have a /temp/ don't worry about it. Also a special message is given to 404 images when the parent directory exists.
  4. The message.txt file is optional. It will appear on every error page generated beneath any message that http_errors generates.
  5. It does not send out emails on each error. Personally, I think that's a waste of resources. And could rather easily be abused to clog up your email account. (Well it could work to prevent this but that would mean a sizable chunk of unnecessary code.)



You can download it in either of the following formats. Unzip them as you would any other compressed file, refer to your unzipping software or operating system for instructions. (6.1 KB)

http_errors.tar.gz ( 5.6 KB)



If you have some experience with Perl, then the comments in the http_errors source should be adequate. However, I have tried to explain everything as clearly as possible in this document. The only thing that must be configured is the first line of the file. And you will need to create a .htaccess file to tell your server to use http_errors.cgi.

  1. #!/usr/bin/perl

    Change the first line in http_errors.cgi to point at perl on your server. The default may work. Type which perl from a Telnet prompt to find the location.

  2. Skip down a few lines to the CONFIGURATION section and set a few variables.
  3. $email Should be a valid email address that will be displayed for users to contact you; this is a good thing to do. If you really don't want to include one just leave it blank. (Not even a space between the quotes.)
  4. $css Optional. It is the path to your Style Sheet. Either use the full URL or the complete path from your root directory.
  5. $title This will be used as the document title as well as a level one heading on the page.
  6. That's all you need to do in the script unless your making additions.


Creating and Editing .htaccess

.htaccess is the directory-level configuration file used by Apache. (.htaccess is the default name, it could be anything.) This is the only place you can do any configuring, given that you're allowed to do any, when you don't have access to the server root. It is a plain text file and comments are denoted with a '#' anything following this mark on the same line is ignored by the server.

You will need to tell your server to use http_errors.cgi. Do this by adding the following lines, edited if necessary, to your .htaccess:

# Error Processing
ErrorDocument 404 /cgi-bin/http_errors.cgi
ErrorDocument 403 /cgi-bin/http_errors.cgi

If you don't have a .htaccess file just open a blank file and put those lines in it. In Win32 you might have trouble naming it with a . at the beginning; name it something else then rename it on the server. Note that some FTP clients may not show these 'dot-files' by default so don't be alarmed if it disappears when you rename it. Incidentally, DOS Edit will allow you to name it correctly.


Creating and Editing message.txt

message.txt will be included in each error page that is generated. Suggested content would be a link to your main index, a site search engine, and link to a site map.

Just create a plain text file and make it readable to http_errors.cgi. This should not be a complete HTML document since it will be inserted within a document. Any uploaded files are typically world readable by default.


Uploading The Files

You should have http_errors.cgi, a .htaccess file, and perhaps a message.txt; now you need to upload them. Any OS worth the silicon its stored on should have a command line FTP. Alternatively you may want to download ws_ftp a popular graphical FTP program.

  1. Be sure to upload the files in ascii.
  2. Upload http_errors.cgi to your /cgi-bin/ then chmod 755 http_errors.cgi (or whatever you need to do to get it executable).
  3. Upload message.txt to /cgi-bin/ as well.
  4. Upload the .htaccess file to your root directory where your main index page is served from. You should not need to change permissions on this file. But chmod 644 .htaccess will do it.



Maybe you screwed up. Alright, I haven't run this on a wide variety of systems and am a novice perl programmer. So if you encounter a problem let me know at <>.

Copyright©2001 Rob -