Skip to content

Exception Handling

Classification of Exceptions

Exceptions are put in these categories:

  1. Unpredictable, technical exceptions, like NullPointerException or MethodNotFoundException. Such exceptions are the symptom of a bug in the software.
  2. Predictable, technical exceptions, often related to network connection and availability problems, e.g. TimeoutException or UnknownHostException
  3. Predictable, non-technical exceptions, also known as ‘Business Exceptions’

How to handle Exceptions

In total, the application takes three different kinds of actions when an exception occurs:

  • tell the user that an exception has occurred and she cannot use the application anymore and terminate the current user session
  • tell the user that an exception has occurred and she can continue to use the application
  • tell the user that a business exception has occurred and optionally what she could do to avoid/resolve this problem

There are two means to tell the user about an exception:

  • stay on the current page and display a message, typically with <p:growl> or <p:messages>
  • navigate to an error page, either to recoverableError.xhtml or unrecoverableError.xhtml

You can programatically navigate to an error page and explicitly add messages to be shown on the error page. This, however, is not the recommended way to show an error page. Instead you should throw one of the exceptions UnrecoverableException and RecoverableException. This is typically being done during the excecution of an JSF event handler. It can even be thrown from within EJBs or other beans that are managed by CDI.

You can parameterize the aforementioned exceptions by means of the enumeration ExceptionHandlerHint in order to control the effect of the exception:

public static enum ExceptionHandlerHint {


There is a centralized exception handling available in AbstractManagedBean, FullAjaxExceptionHandler and PrimeExceptionHandler. That exception handling does the message display and error page navigation in a generalized way. The only thing you need to take care of is to decide, which exception type to throw and how to parameterize the exception object.


The error page location depends on the used template. That is taken care of in the overwritten versions of the exception handlers FullAjaxExceptionHandler and PrimeExceptionHandler.