Docs

Docs

Configuration

System properties and runtime knobs for tuning SwingBridge.

This page lists the runtime knobs SwingBridge reads from JVM system properties, plus the in‑page error view that activates when the embedded Swing application fails to launch.

System Properties Reference

Property Default Description

java.awt.headless

—

Required. Must be set to false. SwingBridge needs a real (non-headless) AWT toolkit to render Swing components into images on the server.

applibs.dir

applibs/ next to the application JAR (or the project root in dev)

Override the directory SwingBridge scans for application JARs. See Using the applibs Directory.

swingbridge.jarlist.baseDir

JVM working directory (user.dir)

Base directory used to resolve relative paths in swing-app-jar-list.conf. See Using swing-app-jar-list.conf.

swingbridge.frameUpdateInterval

100 (milliseconds, minimum 71)

How often SwingBridge polls each Swing window for changes and pushes the dirty regions to the browser. Lower values feel more responsive at the cost of CPU; higher values save CPU at the cost of perceived latency.

swingbridge.errorReporting.enabled

true

When set to false, the launch-failure error view shows only the failure header — the exception type, message, and stack trace are suppressed and the report-submission form is hidden. See Launch Failure Error View below.

For Spring Boot, set system properties through <systemPropertyVariables> on the spring-boot-maven-plugin (see Project Setup) or pass -D flags on the command line. For a packaged JAR, pass them with -D on the command line:

Source code
terminal
java -Dswingbridge.errorReporting.enabled=false -jar my-app.jar

Launch Failure Error View

When a Swing application embedded via [classname]`SwingBridge` fails to start — for example because the configured main class cannot be loaded, the AWT toolkit cannot initialize, or no JFrame becomes visible within the launch timeout — the canvas area is replaced with an in-page error view that shows:

  • A failure title and a short explainer.

  • The error type and message.

  • The full stack trace, including any Caused by chain (collapsible).

  • An optional email field and a Submit report button that posts a report to Vaadin so the cause can be investigated.

  • A Preview report content button that opens a draggable, resizable dialog showing the exact JSON that would be submitted (with the stack trace rendered as plain text in a separate section).

  • A link to the Vaadin Privacy Policy explaining how reports are processed.

The intent is that a developer integrating SwingBridge sees a meaningful error in the browser instead of a blank canvas.

Disabling for Production

Set swingbridge.errorReporting.enabled=false to suppress all exception details in the error view. Only the Failed to launch the Swing application header is shown; the message, stack trace, email field, and submit button are all hidden so that no diagnostic information leaks into the page or onto a report endpoint. Diagnose the cause from server-side logs instead.

For a Spring Boot run, add the flag to the <jvmArguments> in spring-boot-maven-plugin. For a packaged JAR:

Source code
terminal
java -Dswingbridge.errorReporting.enabled=false -jar my-app.jar
Important

Stack traces can contain customer data (file paths, hostnames, query parameters). Disable error reporting in any deployment where this information must not reach end-users or third parties.

Updated –