Enterprise Software

Configuring error messages for Apache includes

When you build a site that uses includes to deliver content, there will inevitably be times when the include fails. Don't rely on the built-in error messages. Give your users better feedback with custom error messages.

It's common to have little components that are generated into your Web server's docroot, which then get included into other pages. For example, you may have a single header file that you include across every page of your site. Or you might have a news ticker where the ticker HTML is generated into a small text file and you just do a virtual include of that news ticker in all the pages where you want to show it. That include would look something like this:
<!—#include virtual="/news/ticker/ticker.html" —>

It's a handy way to build content in one place and easily use it anywhere you want on your site. But what happens if the ticker hasn't generated properly for today? In this particular example, probably nothing—the previous news ticker HTML, the one generated yesterday, would still be sitting in the docroot. So all that would happen from the user's point of view is that your page would be showing a news ticker that's a day old. Nothing fatal, not a terrible user experience at all.

Setting the default error message
But suppose you've got a more complicated setup. Suppose you're building a stock ticker system and, in one of your pages, you have a URL structure like this:

We're assuming that the query string (everything after the question mark) contains the stock symbol. So, inside your news.html page, you might have another include, like this:
<!—#include virtual="/news/ticker/${QUERY_STRING}.html" —>

This include pulls in a component that has news stories specifically for this stock symbol. But if a user somehow has a mistake in the URL, an invalid stock symbol that hasn't been generated into your docroot, the above include will not find an HTML file sitting out there to pull in. It will throw an error. You've probably seen this error on many Web sites; it's the default Apache include error:
[an error occurred while processing this directive]

Okay, that's ugly. First off, you should configure the global error message instead of just leaving it to the default that's coded into mod_include. In your httpd.conf file, you should put a directive like this:
<IfModule mod_include.c>
SSIErrorMsg "<!— missing include —>"

In this particular example, we've coded the default error message to be an HTML comment; so, if an error occurs, users won't see it at all unless they open up the HTML of your page.

Setting a per-request error message
That's well and good, but there are still times when you might want to have a specific kind of error message. You're in luck, because Apache and mod_include support a per-request override of the error message. Back to our stock ticker example, you could put something like the following in the news.html page where you're doing the include:
<!—#config errmsg="${QUERY_STRING} is not a recognized symbol" —>
<!—#include virtual="/news/ticker/${QUERY_STRING}.html" —>

If the include can find the given file, everything's okay and all your content renders normally. If it can't find the file, users will see a message on the page that tells them the symbol they entered was not recognized. This is a much better user experience.

You do have to be aware of one thing—the errmsg persists for the length of this request. So if you have other includes farther down the page that might throw errors, you should reset the errmsg variable to something appropriate. But the errmsg does not persist across requests, so other pages with other includes are not affected by the error message you set in this page.

Editor's Picks