Troubleshooting

Common SwingBridge launch failures and how to fix them.

Common Failure Modes

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

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.

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.

Docs

Docs

Troubleshooting

Common Failure Modes