Custom error pages for Tomcat JSF applications

Sunday March 11, 2012 ()

In this blog we will demonstrate how and where to catch Tomcat application page access errors and display custom error pages to users.

Tomcat Instance Errors

Page access errors coming from Tomcat itself are those errors outside any application. Misspelled application names, etc. fall into this type of error. Tomcat will also throw a 500 error when a page is accessed while the application is being deployed.

These errors can be caught in the web.xml of the Tomcat instance. In Debian servers, this web.xml file can be found in {CATALINA_HOME}/conf.

Enter the following to catch 404 and 500 errors before the closing </web-app> tag of this file.


location is relative to your root. Root could be the default ROOT or root of the application you designated as root. Please make sure your new entry is well-formed or your Tomcat will stop running.

Application Error Pages

Consider the following servlet url-pattern mapping entry found in the web.xml of your application.

	<servlet-name>Faces Servlet</servlet-name>
	<servlet-name>Faces Servlet</servlet-name>

If a missing page with an extension of xhtml is accessed from your application, it will yield a This is because these files are processed by javax.faces.webapp.FacesServlet. A missing page that do not have the xhtml extension (or without extension at all) will give you a 404 error.

Internal Servlet exceptions error pages are displayed as a result of javax.servlet.ServletException being thrown. This could be an error in or code or in a code used by your program.

The errors mentioned are caught in the application web.xml file. Edit file and add the following, also before the closing </web-app> tag. Note that location is also relative to your ROOT.


The 404 error page can be any HTML or a JSF page that may contain the custom message you want to relay to your visitor.

For java exception based page errors, you may either display a plain HTML or control the page from a backing code. Below is an example of how to display the stack trace of an exception from backing bean into the error page view.

String trace;

public String getStackTrace() {

    FacesContext context = FacesContext.getCurrentInstance();
    Map requestMap = context.getExternalContext().getRequestMap();
    Throwable ex = 
		(Throwable) requestMap.get("javax.servlet.error.exception");

    StringWriter sw = new StringWriter();
    PrintWriter pw = new PrintWriter(sw);
    trace = sw.toString();

    return trace;


The page snippet below which is part of error_exception.xhtml (line 7 of error-code location) will display the exception stack trace using the above backing code.

<h:outputText escape="false" value="#{errorPageBean.stackTrace}" />

Error page when Tomcat is down

If a Tomcat application is accessed when the Tomcat server is down (not running), Apache will display a "Service temporarily unavailable" message, a 503 error. The error can be caught through your virtual host directive entries but ONLY if Tomcat receive requests through Apache (See this blog to setup Tomcat as your main webserver through Apache using mod_jk). See the virtualhost entry below.

<virtualhost ... >
	DocumentRoot /var/www
	<Directory /var/www/error>
		Order allow,deny
		Allow from all

	#ErrorDocument 404 /errors/error_404.html
	#ErrorDocument 503 /errors/error_500.html
	# Or
	ErrorDocument 404
	ErrorDocument 503

In Debian servers, the Apache site configuration files are located in /etc/apache2/sites-available.

Save changes, and restart both Tomcat and Apache.

That's it, good luck.


Comments (Custom error pages for Tomcat JSF applications )