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.
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.
<!-- Define an error handler for 404 pages --> <error-page> <error-code>404</error-code> <location>/error404.jsp</location> </error-page>
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.
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:
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.
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.
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 URL: http://yourdomain.com/someIncorrectURL
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