> Markdown version of [Troubleshooting](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/troubleshooting). Section index: [llms.txt](https://vaadin.com/docs/v25/tools/llms.txt)

# <a id="swing-bridge.troubleshooting"></a>Troubleshooting

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](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/configuration.md#swing-bridge.configuration.error-reporting)). Use the table below to map the error you see in that view (or in the server log) to the most likely fix.

## <a id="swing-bridge.troubleshooting.failure-modes"></a>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](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/installation-from-scratch.md#swing-bridge.installation-from-scratch.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](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/adding-your-app.md#swing-bridge.adding-your-app.jar-loading).                          |
| 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.                |
| The view stays empty in the browser — no canvas, no error view — even though the server log shows the Swing application launching (frame created, no exceptions).                          | Server push is not enabled. SwingBridge streams the rendered frames from a background AWT thread, which requires push; without it the updates are queued server-side and never delivered. Annotate your application shell class (the `AppShellConfigurator` implementation) with `@Push`. See [Enable Server Push](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/installation-from-scratch.md#swing-bridge.installation-from-scratch.push). |
| 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](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/installation-from-scratch.md#swing-bridge.installation-from-scratch.license).                                                                                                                                                                                                    |