Custom Error Pages in Tomcat - Part 1

Author: Neale Rudd, Metawerx

Date: 29-Sep-2006

Custom error pages can be used to display a branded error page if your application crashes, to notify the site developer of problems occurring on the site by email, or to provide more information to the user who experienced the error.

Tomcat provides powerful methods to assist in developing custom error pages, allowing anything from simple HTML, to more complex error handlers written in JSP, with separate pages per error type or HTTP error code.

This tutorial focusses on creating an error handler page in JSP.

Of course, it is important that the error page itself doesn't throw any errors, as this can make debugging it quite difficult. While developing your custom error page, this is a problem you will most likely experience. See Debugging a Custom Error Page for more information.

First steps

The first thing your JSP error handler page must have, is a tag at the top letting Tomcat know it is an error page.

This is achieved using the following tag:

<%@ page isErrorPage="true" %>

First, let's create a simple error page for handling 404 errors (Page Not Found errors) called /error404.jsp. Place this file in your application root.

<%@ page isErrorPage="true" %>
<h1>A 404 error has occurred</h1>
We apologise, but the page you have specified cannot be found.

Next, in web.xml, define a handler for this error page by adding the following code between the <web-app> tags.

<!-- Define an error handler for 404 pages --> 

The <error-page> element can accept HTTP error-codes or exceptions. In the above example, we are specifying that 404 errors should trigger our new /error404.jsp page. For more information, see the <error-page> element.

After restarting your application, using the Tomcat Manager, try an invalid URL, and the error page should be displayed.

If you are using Internet Explorer, you might still get the standard Internet Explorer Friendly HTTP Error Message. We are going to add some code to avoid that page showing in the next section.

  • Interesting point - on Tomcat 6, I've found that you can specify an html page as a 404 error page (eg: error404.htm), and don't need the page directive at the top of the page either. However, it only seems to work with 404 errors that have a 3-character extension. This is quite misleading as it can make you believe your 404 error page is working correctly when it's actually not. For example /sfsdgsdg.sgs will redirect to the error page, but /sfsdgsdg, / and /sfsdgsdg.sgsa will throw errors instead. So therefore, please use a JSP page and add the page directive as explained above.

Avoiding Internet Explorer's "Friendly HTTP Error Message"

Internet Explorer has a feature called Show friendly HTTP error messages, which is enabled by default in Tools -> Internet Options -> Advanced.

This feature overrides error pages sent by the web server and displays the default Internet Explorer 404 error page instead, which explains the problem to the user in greater detail, in the user's preferred language.

The rules Internet Explorer uses to decide when to display this page are as follows:

  • the page has been sent with an HTTP error code (eg: 404)
  • the page is less than 513 bytes long

Therefore, we are going to make our page at least 513 bytes long, by including the following comment. Place this text after the JSP directive <%@ page isErrorPage="true" %>.

Unless this text is here, if your page is less than 513 bytes, Internet Explorer will display it's "Friendly HTTP Error Message",
and your custom error will never be displayed.  This text is just used as filler.
This is a useless buffer to fill the page to 513 bytes to avoid display of Friendly Error Pages in Internet Explorer
This is a useless buffer to fill the page to 513 bytes to avoid display of Friendly Error Pages in Internet Explorer
This is a useless buffer to fill the page to 513 bytes to avoid display of Friendly Error Pages in Internet Explorer

This comment can be removed if your error page output size definitely exceeds 513 bytes. However, our short example above does not, so we will include this comment.

Getting information about the error

To determine more information about the error which occurred, we can use the ErrorData class, which is available from pageContext.

As the JSP page was marked as an errorPage with the isErrorPage directive above, we also have access to a variable called "exception" of type java.lang.Throwable. However, as this is a 404 error, exception will be set to null.

In the next block of code, we will attempt to get the ErrorData object. This data is not always available, so we will fail gracefully if we can't retrieve it.

Add the following java scriptlet code at the end of your error page.

    boolean handled = false// Set to true after handling the error
    // Get the PageContext
    if(pageContext != null) {
        // Get the ErrorData
        ErrorData ed = null;
        try {
            ed = pageContext.getErrorData();
        catch(NullPointerException ne) {
            // If the error page was accessed directly, a NullPointerException
            // is thrown at (
            // Catch and ignore it... it effectively means we can't use the ErrorData

        // Display error details for the user
        if(ed != null) {
            // Output this part in HTML just for fun
                <p />Error Data is available.
            // Output details about the HTTP error
            // (this should show error code 404, and the name of the missing page)
            out.println("<br />ErrorCode: " + ed.getStatusCode());
            out.println("<br />URL: " + ed.getRequestURI());
            // Error handled successfully, set a flag
            handled = true;
    // Check if the error was handled
    if(!handled) {
        <p />No information about this error was available.

After making the above changes, try causing a 404 error by visiting an invalid URL. Also try accessing the error page directly.

When a 404 error occurs, the following will be displayed:

Error Data is available.
ErrorCode: 404

When the page is accessed directly, the following will be displayed:

No information about this error was available.

This tutorial will be continued at a later date, in Custom Error Pages in Tomcat - Part 2

metawerx specific

referring pages