How to manage error pages in Java web sites

Use case

When browsing the Internet I am really surprised how often you get a dirty blank page instead of a nice custom error page even in first class web sites. One fresh example is Jumo which has just been launched (aim is to be a non commercial social network focus on NGOs and humanitarian actions – initiative we are definitely supporting anyway at Java-Hoster – at the opposite of Facebook) and is already down because of the huge traffic it has received during its first moments. For hours you had this default blank page telling something wrong happened.


Somehow it is kind of good news for them, however it could have been much sexier with a 2 minute work.

This is just a fresh example I have in mind, however you’ll find plenty of them all over the web !
To avoid such mistake, just follow the tutorial just below !

Java technology is over PHP technology

When it comes to managing errors in web applications it could be quickly a mess, especially if you get a PHP site hosted by a cheap hosting provider located somewhere because you need to get access to “http.conf” which is not allowed on shared hosting, or to .htaccess which is not installed … Then the last choice is to build a custom mechanism to manage errors whether they are on server side or on client side. I am sure you’ll be happy to have to handle this part as well.

If you decided to build your website using Java EE technologies (and Java-Hoster will be happy to host it) you should be proud of your choice because you only need few lines of configuration in your web.xml to enjoy the Java built-in features to manage errors, whatever your hosting provide is. Indeed, since the beginning JEE allows a very easy maintenance and set up of custom error pages using a native mechanism.

HTTP standard error codes

Just a section to remind what are the existing http errors we can face, each error type is associated with a server returned http error code :
(see http1.1 spec for more info)

- class 1 return codes (1xx) : Information
This one is a new return code which is not 100% supported and normally and only provides information to the client about the request.

- class 2 return codes (2xx) : Success response, the request has been correctly executed –> expected answer from server (http code 200).

class 3 return codes (3xx) : Redirection response. The resource has moved and is not any more at this URL.

Here are the errors we will be interested in.

- class 4 return codes (4xx) : Error on client side. Probably most known of all is error 404 : Not Found
Such errors indicate something went wrong on the client side probably a mistake in the requested URL. This is not an issue you can avoid however displaying something sexy doesn’t cost that much.

- class 5 return codes (5xx) : Error on client side. Something went wrong on the server in that case it can data access issue, bugs, etc… but it is developers responsibility and in that case displaying something which tells the user “his action has been cancelled because of a technical problem” is mandatory. Otherwise this guy can wait for while before he receive his confirmation…

How to fix it

Create your custom error pages

First of all you have to design the pages you want to display to user in case of error : let’s say 2 pages, 1 for 4xx errors and another for 5xx errors (however another for 3xx can be useful). You can use whatever you want (html, jsp, jsf, etc…) but be aware that if something went wrong on server side maybe your Tomcat server is having issues and therefore you shouldn’t be charging it with jsp pages or something else. That is why I always recommend to build error pages using HTML.

Now we have :
– 400.html –> telling the user did something wrong
– 500.html –> telling the server did something wrong

Add it to your deployment descriptor (web.xml)

Now the only thing we have to do is to is to say our J2EE server we want to use these pages in case of errors. Since only integers are allowed for error-code we can not use patterns, so we list all of them (full http errors list).


That’s it, you know how to display nice error pages to your customers with a 2 minute job
–> see example on Java-Hoster

Next step will be to display error pages in several languages.

About Matthieu

Hello, I joined Java-Hoster in 2009. After my engineering studies in France, I worked for several companies including some well known Natixis , Airbus and Air France . Now I am more focused and involved on Java open-source projects and of course in Java-Hoster which makes me learn a lot and feed me as well :-D I am also responsible for this blog, so if you have something to say about it feel free to contact me. Cheers.
This entry was posted in Java course, Java for Web and tagged , , , , , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>