25 Years of Programming
An open source source for C, C++, OWL, BASIC, MDB, XLS, DOT, and more...

Home Projects Sitemap Search Blog Forum+Chat About Us Privacy Terms of Use Feedback FAQ Images Services Payments Humor Music

How to create and install a custom Apache 404 error document, step by step

This article has step-by-step instructions and template code for creating a custom 404 Page Not Found Apache error document for your website. It looks like a long process, but it's not. Like all my How To's, it gives detailed instructions for every step, for someone who's never done that step before.

I did not find the method at cPanel > Error pages to be helpful or useful. It's better to do the creation of this document yourself.

1) Create the file for your error document

In the public_html folder of your website, create a new file called 404.shtml. The name doesn't have to be 404, but the extension should be .shtml if you want to use any of the SSI (Apache Server Side Includes) code in the template code below. It customizes the output for your site and displays the filename that wasn't found.

a) Create the file in FrontPage, Dreamweaver...

You can create 404.shtml in whatever web design software you use. Put it in your top level directory so it will be published to public_html.

b) Or create the file in cPanel

Go to cPanel > File Manager.
Navigate to public_html.
Click on the text of the Create New File link (about halfway down the page).
In the file name box, enter 404.shtml.
For file type, select Text Document (it's really an HTML document, but if you select that option, it inserts a bunch of text that you'd delete anyway).
Click Create. This will create the document.
Find 404.shtml in the file list and click on its name (not the icon next to it).
In the upper right corner of the screen, click Edit File.
Copy the template code below and paste it into the box.
Customize the pasted text for your website.
Click Save.

2) Use .htaccess to tell Apache to use your new error document instead of the default one

In cPanel > File Manager > public_html, find .htaccess
Click on its name.
In the upper right corner, click Edit File
Insert into the file, at any location that is not enclosed in HTML style tags such as <tag></tag>, the following line. The path MUST be a local URL that starts with /. Do not use http://yoursite.com/...:

ErrorDocument 404 /404.shtml
Click Save.
Test your new error document in your browser by trying to go to a page you know doesn't exist.
You should see your new error document, and you're done!

Troubleshooting:

If the variables such as the website name, file name, server name, and port number aren't showing on the page, Apache Server Side Includes might not be enabled. In public_html/.htaccess, at any location that is not enclosed in HTML style tags such as <tag></tag>, add one of these lines. The first one is more secure:

Options +IncludesNOEXEC
Options +Includes
Questions, comments, assistance in the Forum.

Notes for customization:

Within an error document, all links and references must be absolute URLs (such as http://yourdomain.com/...), not relative or local ones.
In addition to the server variables I used in the code below, you can use other Server-Variables shown in the gray table in the RewriteCond section of http://httpd.apache.org/docs/1.3/mod/mod_rewrite.html.

Variations:

If your error document doesn't use Apache SSI features, it can have a file extension other than .shtml, such as .html, .htm, .php, whatever you normally use for web pages.

Also, you can put your error document in a folder other than public_html, such as public_html/errordocuments/... In that case, revise your ErrorDocument line to:

ErrorDocument 404 /errordocuments/404.shtml

If you do this and if you don't want Apache SSI enabled for your entire site, you can create an .htaccess file in /errordocuments and move the Options +IncludesNOEXEC line into it so that it only enables SSI for your errordocuments folder.

If you are on Lunarpages shared hosting, Options +Includes appears to be the default setting for the entire site. If you don't use SSI except for error documents, and want to turn SSI off for the rest of your site, you can put the following line in public_html/.htaccess:

Options -Includes

Reference materials:

http://httpd.apache.org/docs/1.3/mod/core.html#errordocument.

Template code for 404.shtml

You can freely use this code as a template for your 404.shtml file:

Red highlighted text requires easy customization for your website and file names.

The one line with Yellow highlighted text is entirely optional, and isn't required at all, even if you normally use stylesheets. It is shown here to demonstrate that you MUST use an absolute URL here even if you normally use relative ones. If you don't use stylesheets, delete the line.

Green highlighted text might need customization if you want this page to match the rest of your site. If you're not sure how to make it match the rest of your site, you can:

Open any existing page of your site
Click Page > View Source in your browser
Find near the top of the code the lines that (will obviously) correspond to the green ones below.
If you don't use a DOCTYPE line, you can delete the one here.
Copy those lines and use them here in place of the green ones.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta http-equiv="Content-Language" content="en-us">
<title>404 - File Not Found</title>
<meta name="keywords" content="404, page, file, URL, not, found, error">
<meta name="description" content="404 - File Not Found">
<link rel="stylesheet" type="text/css" href="http://yourdomain.com/stylesheet.css">
</head>
<body>
<h1>Not Found</h1>

<p>The requested page or file was not found:</p>
<p><b><!--#echo var="HTTP_HOST" --><!--#echo var="REQUEST_URI" --></b></p>

<p>This could be because of a broken or outdated hyperlink, a typing error, or the page might not exist anymore.</p>

<p>Our <a title="Sitemap" href="http://yourdomain.com/sitemap.htm"><b>Sitemap</b></a> 
might help find the page or a page that replaced it.</p>

<p>&nbsp;</p>
<hr>

<!--#echo var="SERVER_SOFTWARE" --> <!--#echo var="HTTP_HOST" -->, Port <!--#echo var="SERVER_PORT" -->

</body>
</html>

Addition 12/26/2007:

Although the above code shows how to use Apache SSI features, I no longer use SSI on my own pages.

Are there security weaknesses in SSI that could make the above code vulnerable to attack? I don't know. However, SSI provides such a trivial benefit to the code above that it was easier just to get rid of it than investigate fully, because...

You can use plain text for the HTTP_HOST. It's your website's name, and is always the same.
Nobody cares what the server software or port is.
The visitor can see the URL of the page that wasn't found, displayed in their browser's address bar.

The security weakness, if any, would be due to the fact that it takes the URI string, which could be anything and came from an outside source, and passes it through to display on the web page. Unfiltered, this could provide the opportunity for a cross-site-scripting (XSS) attack.