Skip to content

Error Window

A Vaadin Flow add-on that displays a modal dialog when an unhandled exception occurs, showing a full stack trace in development mode and a reportable error code in production mode.

Overview

Use the Error Window add-on when you want a consistent, user-friendly error experience across your Vaadin application. The add-on registers itself automatically via VaadinServiceInitListener — no configuration required — and intercepts all unhandled exceptions at the session level. You can also trigger the error dialog manually for caught exceptions using ErrorManager.showError(e).

Features

  • Automatic registration via Java SPI (VaadinServiceInitListener) — zero configuration for the common case.
  • Development mode: shows the exception message, a collapsible stack trace, and a button to copy the full trace to the clipboard.
  • Production mode: shows a UUID error code with instructions to report it to the system administrator; no stack trace is exposed.
  • Manual invocation via ErrorManager.showError(Throwable) for caught exceptions.
  • Pluggable ErrorWindowFactory per exception type — customize the dialog for specific Throwable subclasses.
  • Full internationalization support via ErrorWindowI18n, including integration with Vaadin's I18NProvider.
  • Draggable, closable dialog with configurable width.

Supported versions

Add-on version Vaadin version
4.x 14–25

Installation

From the Vaadin Directory

Available in the Vaadin Directory.

Maven dependency

<dependency>
    <groupId>com.flowingcode.vaadin.addons</groupId>
    <artifactId>error-window-vaadin</artifactId>
    <version>X.Y.Z</version>
</dependency>

Replace X.Y.Z with the latest released version. Add the Vaadin add-ons repository to your pom.xml:

<repository>
    <id>vaadin-addons</id>
    <url>https://maven.vaadin.com/vaadin-addons</url>
</repository>

For snapshot builds, see maven.flowingcode.com/snapshots.

JavaDoc is published at javadoc.flowingcode.com.

Usage

Automatic error handling

Once the dependency is on the classpath, the add-on registers itself automatically. All unhandled exceptions in any Vaadin session are intercepted and displayed in an ErrorWindow dialog — no further setup is needed.

Manual invocation

To show the dialog for a caught exception, call ErrorManager.showError:

import com.flowingcode.vaadin.addons.errorwindow.ErrorManager;

Button button = new Button("Parse", event -> {
    try {
        int value = Integer.parseInt(inputField.getValue());
    } catch (NumberFormatException e) {
        ErrorManager.showError(e);
    }
});

Supply a custom message alongside the throwable:

ErrorManager.showError(e, "Failed to process the uploaded file.");

Customizing the dialog with i18n

Override individual labels using ErrorWindowI18n:

ErrorWindowI18n i18n = ErrorWindowI18n.createDefault();
i18n.setCaption("Se produjo un error");
i18n.setInstructions("Por favor, reporte el siguiente código al administrador del sistema");
i18n.setClose("Cerrar");
i18n.setDetails("Ver detalles del error");
i18n.setClipboard("Copiar detalles al portapapeles");

new ErrorWindow(throwable, i18n).open();

Integrate with Vaadin's I18NProvider using the translation key factory:

ErrorWindowI18n i18n = ErrorWindowI18n.create(getTranslation::apply);

The translation keys are:

Key Default value
com.flowingcode.vaadin.addons.errorwindow.caption An error has occurred
com.flowingcode.vaadin.addons.errorwindow.instructions Please report the following code to your system administrator
com.flowingcode.vaadin.addons.errorwindow.close Close
com.flowingcode.vaadin.addons.errorwindow.details Show error details
com.flowingcode.vaadin.addons.errorwindow.defaultErrorMessage Please contact the system administrator for more information.
com.flowingcode.vaadin.addons.errorwindow.clipboard Copy details to clipboard

Custom factory per exception type

Register a custom ErrorWindowFactory to handle specific exception types differently:

// Custom dialog for a specific exception type
ErrorManager.setErrorWindowFactory(MyBusinessException.class, details ->
    new ErrorWindow(details.getThrowable(),
        ErrorWindowI18n.createDefault()).open());

// Override the default factory for all other exceptions
ErrorManager.setErrorWindowFactory(details ->
    new ErrorWindow(details.getThrowable(),
        ErrorWindowI18n.createDefault()).open());

Special configuration when using Spring

When running on Spring, allow-list the com.flowingcode package so Vaadin Flow can discover the add-on's components. See Common configuration for details.

API reference

Headline types exposed by the add-on:

  • ErrorWindow — the modal error dialog; extends Dialog.
  • ErrorWindow(Throwable cause) — auto-detects production mode; uses default i18n.
  • ErrorWindow(Throwable cause, ErrorWindowI18n i18n) — auto-detects production mode; uses custom i18n.

  • ErrorWindow(ErrorDetails errorDetails) / ErrorWindow(ErrorDetails errorDetails, ErrorWindowI18n i18n) — construct from an ErrorDetails value object.

  • ErrorManager — static utility for showing errors and managing factories.

  • showError(Throwable throwable) — shows the error dialog using the throwable's localized message.
  • showError(Throwable throwable, String cause) — shows the error dialog with a custom cause message.
  • setErrorWindowFactory(ErrorWindowFactory) — replace the default factory for all exceptions.
  • setErrorWindowFactory(Class<? extends Throwable>, ErrorWindowFactory) — register a factory for a specific exception type.

  • getErrorWindowFactory() / getErrorWindowFactory(Class<?>) — retrieve the active factory.

  • ErrorWindowFactory — interface for custom error window implementations.

  • showError(ErrorDetails details) — called to display the error.

  • isProductionMode() — default implementation reads the errorWindowProductionMode or productionMode system property, then falls back to Vaadin's deployment configuration.

  • ErrorWindowI18n — i18n configuration object.

  • createDefault() — static factory with default English strings.
  • create(SerializableFunction<String, String>) — static factory backed by a translation function.

  • Setters and getters for: caption, instructions, close, details, defaultErrorMessage, clipboard.

  • ErrorDetails — value object wrapping a Throwable and an optional cause message; used by ErrorWindowFactory.

For the full API surface, browse the published JavaDoc.

Demo

A live demo is available at addonsv25.flowingcode.com/error-window. To run the demo locally:

git clone https://github.com/FlowingCode/ErrorWindowAddon.git
cd ErrorWindowAddon
mvn clean install jetty:run

Then open http://localhost:8080/.

Source code

ErrorWindowAddon on GitHub — distributed under Apache License 2.0.