Login

Custom Error Pages with Apache

Nobody enjoys seeing an error page. It’s worse if the error page gives you little or no information to help you find the page you were trying to reach. Fortunately, there are ways to configure Apache so that your visitors need never feel so abandoned. This article explains how to set up custom error pages with Apache.

Apache, as you know, is the most popular web server in use today. Since it is historically easily installed, easily configured and very flexible, it’s not difficult to see why. Many of the easily configured options that are possible with Apache, however, are not exploited to their fullest. Most of Apache’s various server configuration options are switched off by default, and although this makes the server much more secure, it also means that a default installation will not take advantage of many of the things that make Apache what it is. The httpd.conf file, Apache’s main configuration file, actually says in section 2: “Note that from this point forward you must specifically allow particular features to be enabled…”

Error messages are certainly a pertinent example of this; Apache can very quickly and easily be set to display almost anything you want, from simple text (yuk) to custom HTML pages or even PHP and Perl scripts. It’s all too common, however, to see the very plain, default error messages that are displayed when the server encounters the standard set of errors, such as the all too familiar 404 or “Page not found” error response. These default pages are ugly, sometimes confusing, very often nothing like the rest of site and almost always detrimental to user experience. There’s no excuse for sticking with these default error pages, especially when it really is so very easy to use alternatives of your own devising.

Anyone reading this is going to be using Apache, if not in production, then at the very least as a development tool, but the browser you use for testing can also have an impact on your work. With the default set up of Apache, if you use Mozilla to try to access a page that does not exist you will see the default Apache server 404 error page, but if you use MS IE5+ you won’t see the default Apache 404. Instead, you’ll see the default Internet Explorer 404 page. This is Microsoft’s so called “friendly error message” which overrides the Apache defaults. The reason for this is that the Apache defaults are all less than 512 bytes.

This overriding featuring of IE can be switched off using the “show friendly error messages” setting in the Tools -> Internet options dialogue, although by default it is set to on, so bear in mind that most people will have this set if they are using IE (which a large number of Internet users are). This isn’t overly important but should be taken into consideration; to overcome this setting automatically, you need to ensure that the pages you wish to use as error pages are larger than 512 bytes. This isn’t too difficult to achieve, but if you aren’t seeing what you should be seeing when creating and testing your error documents, it would be wise to check the file size of your error pages or disable this feature in IE.

{mospagebreak title=Creating a custom error page}

Configuring Apache to serve customized error pages is extremely easy; there is a section of the httpd.conf file devoted to this. It takes just one directive per error to achieve. If you open the conf file and scroll right down to almost the very bottom of section two, you’ll see the section you need to edit:

By default, these directives are commented out, but all you need to do is un-comment each directive and then change the path to point to your own error page:

ErrorDocument 404 /errordocs/404error.html

Quite simply, this statement is broken down into the directive name, the error code and the path to the document you wish to use. You could substitute this last part simply for text enclosed within double-quotes to specify the text to be displayed on the page, but this is hardly an improvement on the default messages themselves. Also, this path could alternatively be the path to a script. As you can see, I’ve put my error documents into a separate folder in my site’s directory structure.

So, very quickly and easily then, you can simply create a series of your own error documents, to cater for the most common server error codes and add the required directive to the conf file. In addition to enhancing the user experience by giving a more pleasant error response, you can also introduce consistency across your site by using CSS to make the pages look like the regular pages of your site. You should also make sure that the pages fit in with other policies in effect on your site; if you pride yourself on your adherence to the accessibility guidelines, for example, you need to ensure that your site map and a help page are linked to from the error pages and that any other applicable guidelines are satisfied. This is common sense anyway, and if you want to provide better error handling from a user’s perspective, you’ll probably want to link to different parts of your site anyway to prevent the error pages from being dead end pages with the user given no choice but to reach for the Back button.

For some different examples of custom error pages, you can view both extremes; at Google for example, the custom error pages simply contain a Google logo and a very brief message. They aren’t overly helpful, but they are consistent with the overall design of the site. Ebay, on the other hand, provides a very large and highly customized error page, with many links and tons of information.

{mospagebreak title=Internationalized error pages}

You needn’t stop there however; if you scroll down through the conf file just a little more, you’ll see a section covering “internationalized error messages” which work on a system of master error pages, containing standard error messages in many different languages, repeated throughout the file:

At run time, when an error occurs, the error page is constructed using server-side includes to build the page from several template html files (bottom, top and spacer), and content-negotiation to grab the actual text for the error message in the preferred language.

If you go to the error page directory in the Apache program folder, which is C:Program FilesApache GroupApache2error on a default Windows installation, you can see all of the internationalized error pages, and within this folder is also the include folder containing the header, footer and spacer pages.

To switch this feature on, you need to copy everything from the Apache error directory to a directory in your sites hierarchy, then uncomment out the block of lines beginning with the Alias directory and ending with the ErrorDocument 506 directive. Finally, the Alias directive needs to be changed so that it shows the path to the directory you have just created; you also need to update the Directory container to show the same path. Don’t forget that the Windows standard backslashes need to be changed to forward slashes before the paths will be accepted by Apache.

When you try this, make sure that you comment out any of the ErrorDocument directives used previously. Also, note that when this is configured correctly and works, you don’t need to worry about whether or not the internationalized error messages will be shown in Internet Explorer – they will, even with the “show friendly error messages” preference set because the server-generated page is greater than 512 bytes.

{mospagebreak title=Maintaining and updating error pages}

You are now faced with the same problem that we initially set out to fix: bland and generally unhelpful error response documents. However, the fact that the server-generated page makes use of included html pages means that you have a centralized method of maintaining and updating these error pages to fit in with your site’s design, making them much easier to customize and manage. If you look at one of the include pages in a text editor, you’ll see a special section there that defines some very basic styles. This is where you can add your own style rules in order to customize the look of the error page.

The 404 response is probably going to be the most common error result that is going to be seen by visitors to your site. Sometimes, this is going to be because they’ve misspelled a URL or clicked on a link to a resource that no longer exists, but very often, it can be the result of site reorganization, or pages being moved from one directory to another within your site’s internal structure. Client redirection is extremely easy to configure; you simply use the Redirect directive, the name of the old directory and the URL of where requests to the old directory are redirected to:

Redirect /olddir/ http://localhost/newdir/

This will only be effective when there are no longer any pages in the olddir directory however, as any request for a page within that directory will be redirected to the newdir, so a request for www.mysite.co.uk/2005/quarter1.html where 2005 is set in the place of olddir will automatically be redirected to www.mysite.co.uk/2006/quarter1.html when http://mysite.co.uk/2006/ is set as the newdir. If just an individual page has been moved, you can simply add a directive specifically for the page that has moved:

You can even use the Redirect directive in conjunction with your customized error pages by making use of the status argument, which comes directly after the directive name. The status can be an error code or one of several keywords. If, for example, a page has been removed from your site rather than just moved, you can add the following directive to your conf file to let visitors know:

Redirect 404 /olddir/deletedpage.html

This will generate the HTTP_GONE.html.var error response when internationalized error messages have been configured.

Apache has many other directives that can be used to deal with ever more complex redirection issues, but these are beyond the scope of this article. You’ve seen how easy it is to configure your own set of custom error response pages, and how to enable customized error responses that can be displayed in a variety of languages depending on the preferences of requesting clients. Additionally, you’ve learned how to redirect browsers when requesting pages that have moved or been removed so you can try to minimize the number of times your custom error pages need to be displayed.