Page tree
Skip to end of metadata
Go to start of metadata


We currently have no big picture concept for error handling. We do have the UI for displaying error notifications or message banners, but do not / cannot use them in a consistant way accross all modules. This concept aims at defining such a general mechanism and guidelines on how to treat errors, exceptions insides apps or modules. This concept should also address the integration with Vaadin, in particular how we deal with Vaadin system errors, such as paint mechanism being broken.


Error handling in Vaadin

1. Component / UI errors

Vaadin comes with a set of mechanisms to handle errors. This is all detailed in the Handling Errors section of the book of Vaadin 7.

Essentially, we can register ErrorHandler objects on any component, up to the UI (root) or even the VaadinSession. If an exception occurs when processing an action, or in an event listener, it will first try to handle that error at the component level, then it will bubble up to the UI and Session. In our case, the safety net for such unhandled exceptions is to register the error handler at the UI or session level, and ask the shell to display an error message. Another interesting use case might be to register error handlers on forms.

2. Internal errors

Still, if an exception occurs in Vaadin internals (e.g. during the paint phase), there is no error handler that can catch it then. This kind of error needs an application restart. Here are two sample stacktraces of such exceptions: vaadin-paint-stacktraces.rtf.

If this happened on initial page load or page refresh, VaadinServlet throws a ServletException and server responds with the 500 status.

Solution: Customize the 500 page by using a redirection in the AdmincentralVaadinServlet.

3. Critical notifications

Otherwise, if the exception occurred subsequently to a UIDL request, Vaadin will show a big red box at the top of the page - they call it a critical notification. What it does is:

  1. Write an artificial UIDL response with an appError metadata, see VaadinServlet#criticalNotification.
    The client shows the critical notification based on the server response.
  2. If the error occurred during the paint phase, it's likely that the UIDL response will be corrupted because of an unterminated chunk.
    The client shows a pure client-side Communication error with a syntax error and its javascript stacktrace (where we can see the corrupted server response).
  3. If an error occurs in the session's DefaultErrorHandler [yeah I managed to corrupt that as well], only then the response has status 500.
    The client then shows a simple dry client-side Communication error.


  1. Write out own artificial UIDL response with the hard-coded RPC call for the shell to show the error message.
  2. Wrap the reponse and its output stream so that critical notification mechanism (1) works as expected, throwing out unterminated UIDL chunks.
  3. First, remove Vaadin's DefaultErrorHandler on the session, then style the client-side critical notification anyway to give that error banner look.



  • introduce something like an ApplicationExceptions for "expected" cases
  • use EventBus for notifying
  • proposal for notifications?
  • container out of date at paint phase sould be treated in an isolated way
  • editing a contact that is then renamed
    • using uuid as itemId?
    • fallback to uuid if itemId is not found?
  • linking to JIRA from the 500 page


  • A servlet filter redirecting to a 500 page if something went wrong in the VaadinServlet (i.e. author instance only)
    • stacktrace
    • link to restart application at last known location => guiding the user
  • Vaadin ErrorHandler on the Vaadin UI
    • sends messages


  • No labels


  1. "...register the error handler at the session level, ..."

    this should be the UI level since we have multiple UIs in the same session and the exception caught relates to only one of them

    1. Right makes sense. Only use case where error handler would be useful on the session is for these critical notifications, the VaadinServlet sends an error event to the session error handler, but since the UI response doesn't get through and we get the client-side communication exception, it does not prove much useful so far.