Application Framework

Error Handling

Unhandled runtime exceptions in the application are handled by a so-called ErrorHandler. By default, linkki shows information about the occurred error within a dialog.

Default error dialog

The default error dialog displays following information about the exception:

  • the cause message

  • the stacktrace if the application doesn’t run in the production mode

On confirmation, the user is redirected to the main application URL and an additional errorOccurred query parameter is added. This parameter enables the target view to react to the error. It can be useful to enable or disable certain features in BeforeLeaveHandler#beforeLeave(BeforeLeaveEvent) in case of an error. For more information refer to Vaadin’s BeforeLeaveEvent.

Customizing the error handling behavior

The ErrorHandler is defined by ApplicationConfig#getErrorHandler(). The default dialog can be customized by creating a different ErrorDialogConfiguration within this method. Following values can be configured:

  • the URL to navigate to on confirmation

  • the caption of the dialog

  • the displayed error message

  • whether the exception cause message should be shown (default: false in production mode, otherwise true)

  • whether the exception stacktrace should be shown (default: false in production mode, otherwise true)

Overriding the used error handler within a concrete implementation of ApplicationConfig
@Override
public ErrorHandler getErrorHandler() {
    var config = ErrorDialogConfiguration.createWithHandlerNavigatingTo(route)
        .withCaption(customCaption)
        .withErrorMessage(customErrorMessage)
        .hideExceptionMessage()
        .hideExceptionStacktrace();
    return new DialogErrorHandler(config);
}

Default Error Page for Exceptions During Navigation

The LinkkiErrorPage offers a comprehensive solution to handle and present all kinds of unhandled errors thrown during navigation. This class serves as a universal and customizable error page designed for linkki applications, but is flexible enough to be adapted by other applications.

Generally no sensitive information should be presented to the user in production mode. Therefore, only a generic error message will be used for any kind of exception - except MessageException. The message of a MessageException will be shown to the user in this error page in development mode as well as in production mode. So be careful with the content that is used as exception message of a MessageException!

No sensitive information must be used in the exception message of a MessageException!

MessageExceptions are only logged if they contain a cause. All other exceptions are logged anyways.

The default implementation of this error page provides the following information and actions that are individually customizable by overwriting respective methods:

Information / Action Default Method to Customize

Title shown in the browser tab

A general short error message

getPageTitle()

Error message

If a MessageException was thrown, the error page shows the message of this exception in production as well as in development mode.

For any other exception it shows a custom message or the exception message in development mode or a generic error message to hide any sensitive information in production mode.

createErrorMessage(ErrorParameter)

Navigation component

A button to navigate to the start view (corresponds to the application context path)

createNavigationButton()

Error details

Timestamp and exception type

createErrorDetails(ErrorParameter)

Logging of the exception

Logs the message of an MessageException if it contains a cause.

For all other exceptions the exception message is logged anyways.

logException(ErrorParameter<Exception>)

In development mode, the exception stack trace is also shown.

Neither the exception message nor the exception stack trace is shown in production mode to avoid revealing security-sensitive information.

Keep this in mind when customizing the error page. Whether the application runs in development mode can be determined by calling isDevelopmentMode().

The error page can be adjusted to the general application layout by creating a subclass that is annotated with @ParentLayout. Nonetheless, the style of the page’s components itselves is fixed and should not be changed.

To use the error page, it has to be included in the Vaadin component scan. If the default page should be used without customizations, this can be done by including the package org.linkki.framework.ui.error in @EnableVaadin. Alternatively in a Spring Boot application, a subclass of LinkkiErrorPage can be created and annotated with @Component to handle the page as a bean. This also allows bean injection that can be used to gather additional application information to be shown by the error page.

Example usage in a Spring Boot application with custom parent layout and page title
@Component
@ParentLayout(CustomAppLayout.class)
public class CustomErrorPage extends LinkkiErrorPage {

    @Serial
    private static final long serialVersionUID = 1L;

    private final String pageTitle;

    // ApplicationInfo must be available as a bean here
    CustomErrorPage(ApplicationInfo applicationInfo) {
        this.pageTitle = applicationInfo.getApplicationName();
    }

    @Override
    public String getPageTitle() {
        return pageTitle;
    }
}