Docs

Docs

Troubleshooting

Common SwingBridge launch failures and how to fix them.

When SwingBridge cannot start the embedded Swing application, the canvas is replaced with an in-page error view that shows the underlying cause (see Launch Failure Error View). Use the table below to map the error you see in that view (or in the server log) to the most likely fix.

Common Failure Modes

Symptom Likely cause and fix

AWTError: Can’t connect to X11 window server using ':0.0' as the value of the DISPLAY variable. (Linux) or UnsatisfiedLinkError loading libawt_xawt.so / awt.dll early in startup.

The runtime JVM flags are missing — specifically --patch-module java.desktop=… and -Xbootclasspath/a:…. Without them the JDK falls back to the native AWT toolkit and tries to open a real display. Apply the full flag set from Project Setup.

HeadlessException on startup, or "no graphics environment" errors.

java.awt.headless is true (or unset and defaulting to true in your environment). Set -Djava.awt.headless=false (or add it under <systemPropertyVariables> in spring-boot-maven-plugin).

Stack trace contains java.lang.ClassNotFoundException: <your.main.Class>.

The Swing application’s main class is not on the SwingBridge classpath. Confirm the JAR is in applibs/ (or named in swing-app-jar-list.conf) and that the fully qualified main-class name passed to [classname]`SwingBridge` matches a class that JAR contains. See JAR Loading Strategies.

Error view says "Swing application did not display any window within the launch timeout."

The Swing application is loading but never makes a JFrame visible — the most common causes are a main method that returns immediately without scheduling work on the EDT, a long-running blocking operation in main, or an unhandled exception in main that gets swallowed before a window is shown. Run the application locally (outside SwingBridge) to confirm it actually opens a window, then check server-side logs for an exception.

Missing or boxed glyphs on Linux ("tofu", squares, replacement characters).

System fonts that the patched font path does not include, or no fonts installed at all. Install the standard fonts your Swing application expects (typically Liberation, DejaVu, or Microsoft Core Fonts on Linux) into one of the standard system font directories (/usr/share/fonts/…​).

License is invalid or trial key prompt on startup.

No valid Vaadin commercial license in ~/.vaadin/ (or %userprofile%\.vaadin\). See License Installation.

Frequently Asked Questions

What is SwingBridge?

SwingBridge is a Vaadin component that allows you to run existing Swing applications in a web browser without rewriting them. It captures the Swing UI as images and streams them to the browser while handling user interactions.

Does the existing Swing code need modification?

Swing applications originally are designed and built with single tenancy in mind. Local resource usages like filesystem access, serial devices etc. should be refactored to achieve full multi-tenancy. Vaadin has relevant tooling to automate code refactoring.

What Swing components are supported?

All standard Swing components are supported, as well as your customized Swing components.

  • JFrame, JDialog, JWindow

  • JPopupMenu and combo box popups

  • JFileChooser (with special upload handling)

  • Tooltips

  • All standard Swing widgets (buttons, text fields, tables, etc.)

How does SwingBridge work?

SwingBridge runs your Swing application on the server and continuously inspects the Swing UI for changes. As soon as a change is detected, dirty regions are streamed to the browser to keep the updates as lightweight as possible. User interactions (clicks, keyboard input) are sent back to the server and replayed on the actual Swing components.

Updated –