Exception Handling and Error Pages

Faces does not let an exception travel up the call stack to the container directly. Whenever code inside the lifecycle throws (an action method, a getter, a listener, a converter that fails in an unexpected way, a template that cannot be built), the runtime catches the exception and publishes an ExceptionQueuedEvent for it. The event is delivered to the one listener that the event context names, the request’s ExceptionHandler, which stores it in a queue. At the end of every lifecycle phase the runtime calls ExceptionHandler.handle(), and that method decides what happens to the queued events.

The default handler of a non-Ajax request takes the first queued event, unwraps it with getRootCause(), wraps the result in a ServletException and throws it, so that an <error-page> of the deployment descriptor, or else the container’s default error page, answers (this is the specification’s description of the default behaviour). The default handler of an Ajax request writes the exception into the partial response instead. Your own handler can do either of those things differently, or something else, and that is what the rest of the page is about.

An exception can also be queued by hand: code that catches an exception and wants the application’s central policy applied to it, but also wants the current phase to continue, publishes the event itself (Queueing an Exception by Hand).

Source: Jakarta Faces 4.1 specification, 6.2 ExceptionHandler and Jakarta Faces 4.1 API: ExceptionHandler

The lifecycle executes each phase, then calls handle() of the request’s handler. A probe handler logged the calls, with the same result on Mojarra and on MyFaces:

Exceptions thrown by the code of a phase reach the handler at the end of that phase, so a failure in Invoke Application is handled before Render Response starts, and a failure inside Render Response is handled at the end of rendering, with part of the response possibly already written. Exceptions thrown by PhaseListener methods are published too, with the extra attributes that tell whether the exception came from the beforePhase or the afterPhase part (What an Event Tells You). The lifecycle chapter describes the phases (the six phases) and phase listeners.

Two phase-specific rules come from the API documentation. If handle() runs in Render Response the recovery options are more limited: calling NavigationHandler.handleNavigation() there is not valid, and since Faces 2.3 the specification says so explicitly. A handler that wants to send the user to an error view from a rendering failure must redirect through the ExternalContext instead, which is what the example below does (the navigation handler is for outcomes returned by actions).

Source: Jakarta Faces 4.1 API: ExceptionHandler and Jakarta Faces 4.1 specification, 6.2 ExceptionHandler

The specification lists exceptions that are part of normal processing and that the ExceptionHandler must not handle: a ValidatorException and a ConverterException where the specification says they are thrown or caught (they become messages and make the component invalid), the MissingResourceException of f:loadBundle, an exception thrown by a @PreDestroy method of a bean (it is logged and not rethrown) and, since the 2.2 change list, AbortProcessingException.

The last one deserves a test, because the two implementations do not behave alike. With no custom handler installed, AbortProcessingException("stop here") thrown from:

With a custom handler installed (ExceptionHandlerFactory and ExceptionHandlerWrapper), the event arrived in handle() on both implementations, from the action method and from the listener alike: the implementations queue it, and the default handler is what ignores it. A probe handler printed the type that arrived. On MyFaces it was AbortProcessingException in both cases. On Mojarra it was AbortProcessingException for the listener and a FacesException wrapping it for the action method, which is why Mojarra’s default handler, which ignores the bare exception, turned the wrapped one into an HTTP 500. A custom handler must therefore unwrap before it decides, and must decide to ignore it explicitly, or every aborted request becomes an error page. The handler of A Complete Handler does.

In the Development project stage both implementations replace the failing response with a debugging page. The pages list the stack trace, the component tree and "Scoped Variables": the request parameters (the run showed lab:missing=missing and the form’s hidden parameter), request, view and session attributes. In an application with a login form the request parameters are what the user typed into it. That is why Development must never reach a production server, and why the project stage is the first thing to check when an error page shows more than a sentence (the configuration page covers jakarta.faces.PROJECT_STAGE and ProjectStage in detail). MyFaces can switch its page off with the context parameter org.apache.myfaces.ERROR_HANDLING set to false: in the run, a Development request then produced Tomcat’s report (HTTP 500) instead of the Faces page. Mojarra has no such switch in the documentation consulted.

Source: Jakarta Faces 4.1 API: ProjectStage

When the container forwards to the location it sets request attributes: jakarta.servlet.error.status_code, jakarta.servlet.error.exception_type, jakarta.servlet.error.exception, jakarta.servlet.error.message and jakarta.servlet.error.request_uri. A debugging page in the scratch application read them with #{requestScope['jakarta.servlet.error.exception_type']}, and showed that what the container sees depends on the implementation (next section). For users, the attributes are developer information: show the status code if you like, never the message or the exception, and escape everything that comes from the request (the request_uri is whatever the client sent).

Tomcat 11.0.26 matched the exception that Faces threw to the container, with these results (Production, all with an error-code 500 fallback, ViewExpiredException, BookNotFoundException and 404 mapped to their own pages):

Mojarra’s default handler rethrows the root cause, so jakarta.servlet.error.exception_type was the application’s own exception class and an exception-type mapping for it matched. MyFaces delivered a ContextAwareELException (the tag exception wrapper of its Facelets EL; exception_type in the debug page), and getRootCause() of the default handler returned it unchanged, because the specification unwraps only the exact classes FacesException and jakarta.el.ELException: the probe handler printed defaultRootCause=...ContextAwareELException for every case. Mapping an application exception type therefore works on Mojarra and not on MyFaces, unless you set the context parameter org.apache.myfaces.WRAP_TAG_EXCEPTIONS_AS_CONTEXT_AWARE to false. In that run MyFaces delivered the unwrapped BookNotFoundException and the mapping matched (and the Ajax error-name became the plain class name, like Mojarra’s). ViewExpiredException is not wrapped and matched on both.

A portable policy maps ViewExpiredException and the status codes (404, 500) and leaves application exception types to a handler that you write (ExceptionHandlerFactory and ExceptionHandlerWrapper) or to the OmniFaces unwrapping filter (OmniFaces FullAjaxExceptionHandler).

A mapping for java.lang.Throwable is a catch-all, and in the run it won over the more specific mappings. The FacesServlet throws a ServletException; the result is consistent with Tomcat matching that wrapper (whose hierarchy reaches Throwable) before it looks at the root cause (Tomcat’s source was not consulted). With

the stale-postback request ended in server-error.xhtml on both implementations, and the specific page was never used. The same mappings with <error-code>500</error-code> in place of the Throwable mapping behaved as expected (the table above). Use the status code 500 as the catch-all next to specific exception types. The OmniFaces documentation gives the same advice. (The mechanism is Tomcat’s and was not run on other containers: check yours.)

Source: Jakarta Faces 4.1 specification, 6.2 ExceptionHandler and OmniFaces Showcase: FullAjaxExceptionHandler

An error page is code like any other and can throw. If the exception handler redirects every failure to the error page, an error page that fails produces a redirect loop: with the page replaced by one that read the failing getter, both implementations redirected until the client gave up (curl stopped after the six redirects it was allowed). Two defences are in the example handler of the next section: it does not redirect again when the request is already for something under /error/, and it redirects to a static page then, a plain HTML file that cannot fail:

Keep error views simple: no database access, no beans with side effects, no dependency on the state of the failed request, and no navigation that needs a session. A container-forwarded error page (without the handler) has the same needs.

Source: Jakarta Faces 4.1 specification, 6.2 ExceptionHandler

The registration is in faces-config.xml, in the <factory> element:

There is no annotation for factories in 4.1. With several <exception-handler-factory> entries in one file, each wraps the one before it, and the one listed last is the outermost: its handler’s handle() runs first. The test: with the OmniFaces factory listed before the Bookshelf factory, an Ajax failure ended in the Bookshelf redirect and the OmniFaces handler never saw the event; with the order reversed, the OmniFaces error page replaced the document. The order of several configuration files is covered in the configuration page.

Source: Jakarta Faces 4.1 API: ExceptionHandlerFactory and Jakarta Faces 4.1 API: ExceptionHandlerWrapper

ExceptionQueuedEventContext is the context of the event:

Source: Jakarta Faces 4.1 API: ExceptionQueuedEventContext

ExceptionHandler.getRootCause(Throwable) unwraps "until the unwrapping encounters an Object whose getClass() is not equal to FacesException.class or jakarta.el.ELException.class`". That is exact class equality, so a subclass of `ELException (MyFaces’s ContextAwareELException) is a root cause for it, and a handler that relies on the method sees the wrapper and not the exception. Write the loop yourself and test with instanceof, as the example does. On Mojarra the thrown type was FacesException for an action and ELException for a getter in a template; both were unwrapped correctly.

The handler of the Bookshelf does the following for each queued event, in order:

It does nothing when the response is already committed (Rendering Failures and the Buffer): there is no recovery to attempt.

Source: Jakarta Faces 4.1 API: ExceptionHandlerWrapper and Jakarta Faces 4.1 specification, 6.2 ExceptionHandler

Results with the handler and the error-page entries of the earlier section, Production, on both implementations:

In headless Chrome the Ajax cases behaved as a user would expect: the browser followed the redirect element and showed the error page (with the reference) or the original page with the note "Your session expired". The reference in the log and on the page matched, with this log line (Mojarra; MyFaces prints INVOKE_APPLICATION(5) and lab:runtime):

The redirect goes through ExternalContext.redirect(), which is Ajax-aware (it writes the redirect element of the partial response), so one code path serves both kinds of request.

The requests behind the table can be reproduced with curl. The first command fetches the page and keeps the session cookie, the second posts the Runtime button like a browser would (both lab=lab and lab_SUBMIT=1 are sent because Mojarra and MyFaces each look at one of them), the third sends the same button as an Ajax request:

Source: Jakarta Faces 4.1 specification, 13. Ajax Integration

Catching an exception inside an action and passing it to the central policy while the action carries on is a legitimate use of the event:

The action completed (the message was added), and at the end of the phase the handler redirected to the error page like for a thrown exception. The ExceptionHandler class documentation shows the same pattern with the call publishEvent(ExceptionQueuedEvent.class, eventContext); that two-argument form does not exist in the 4.1 Application API, which has publishEvent(FacesContext, Class, Object) and a four-argument variant, so copy the three-argument call above.

Source: Jakarta Faces 4.1 API: ExceptionHandler and Jakarta Faces 4.1 API: Application

A redirect needs an uncommitted response. Facelets writes the page into a buffer and flushes it as the buffer fills, so the first bytes of a long page may already be on the wire when a getter fails near the end. The context parameter jakarta.faces.FACELETS_BUFFER_SIZE (documented with a default of 1024 bytes by Mojarra, whose description adds that a larger buffer guarantees, during development, that an error cannot arrive after the response was partially flushed) decides how much can be retracted. With the default, a page that wrote 3 KB of text before it failed could still be redirected on both implementations (the servlet container’s own response buffer also counts); a page that wrote 20 KB and then failed was already committed:

With 200 KB of text and the 64 KB buffer, the response was committed again: Mojarra logged Skipping attempt to set buffer size on a committed response and appended the container’s mapped error page to the truncated content; MyFaces just truncated it. A response whose status is 200 and whose content stops in the middle cannot be repaired by any handler; it can only be avoided by keeping the part that is rendered before a possible failure small, by loading the data before rendering (in a viewAction, or in the action of the previous request) so that a failure happens while the response is still empty, or by raising the buffer to the size of your largest page and accepting the memory per request. The handler above, given a committed response, passes the event to the wrapped handler so that the default behaviour (container page, truncated response) at least applies, and the log still has the exception. The PrimeFaces documentation says the same about FACELETS_BUFFER_SIZE, calling it a limitation of every handler.

Source: Jakarta Faces 4.1 specification, 6.2 ExceptionHandler and Mojarra 4.1 CONTEXT-PARAMS.md

A site-wide script registered with faces.ajax.addOnError gives every f:ajax the same reaction without touching the pages. The script below follows the lessons of the Ajax page: it matches errorName with includes, never shows the server’s message, logs the details to the console only, and reloads on an expired view.

In Chrome, on both implementations, the failing Ajax button showed The request failed. Please try again., and the Ajax button of a page whose session cookie had been deleted reloaded the page (a marker variable set on the old document was gone). Neither the exception class nor the message reached the page. The script does not replace the server side: it does not stop the detail from being sent, and a script can be bypassed.

Source: Jakarta EE Tutorial: Handling Errors and Jakarta Faces 4.1 JavaScript documentation: faces.ajax