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

# <a id="swing-bridge.configuration"></a>Configuration

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.

## <a id="swing-bridge.configuration.system-properties"></a>System Properties Reference

Every parameter below is a JVM system property. None of them is required except `java.awt.headless`; the defaults are chosen so that a deployment can leave all of them unset.

### <a id="swing-bridge.configuration.system-properties.core"></a>Core

| 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](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/adding-your-app.md#swing-bridge.adding-your-app.jar-loading.applibs).                                                                                                              |
| `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`](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/adding-your-app.md#swing-bridge.adding-your-app.jar-loading.jar-list).                                                                                          |
| `swingbridge.rcp.cluster.dir`        | —                                                                   | **NetBeans RCP only.** Absolute path to a pre-built NetBeans Platform distribution directory; the highest-priority discovery source for `NetBeansRcpBridge`. See [NetBeans RCP → Cluster Discovery](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/netbeans-rcp/configuration.md#swing-bridge.netbeans-rcp.configuration.discovery). |
| `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](#swing-bridge.configuration.error-reporting) below.                                                                               |

### <a id="swing-bridge.configuration.system-properties.display"></a>Display and Rendering

These decide what the Swing application is told about the screen and how each window’s back buffer is allocated. See [Display and Rendering](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/rendering.md#swing-bridge.rendering) for the accepted values and what they do.

| Property                           | Default    | Description                                                                                                                              |
| ---------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `swingbridge.screenSize`           | `per-user` | The screen size reported to the Swing application: derived from each session’s own browser, or a fixed `<width>x<height>`.               |
| `swingbridge.hidpi`                | `off`      | Renders the back buffer at the browser’s device pixel ratio, for crisp text on Retina and 4K displays. `auto`, or a fixed decimal scale. |
| `swingbridge.hidpiMaxScale`        | `2.0`      | Upper bound on the HiDPI multiplier, between `1.0` and `4.0`.                                                                            |
| `swingbridge.hidpiMaxBufferPixels` | `8000000`  | Upper bound on a single window’s back buffer, in device pixels.                                                                          |
| `swingbridge.backBufferType`       | `adaptive` | Pixel format of each window’s back buffer: `adaptive`, `argb`, or `565`.                                                                 |

### <a id="swing-bridge.configuration.system-properties.input"></a>Input

| Property                          | Default                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `swingbridge.autoFocusOnAttach`   | `true`                             | The canvas adopts browser focus when it appears, so keystrokes reach the Swing application without the user clicking it first. It only takes focus when nobody else is using it — an unfocused page, another surface of the same bridge, or the navigation control that brought the user to the view; fields and buttons keep their focus, and popup, combo-popup and tooltip canvases never adopt focus at all. Set to `false` to disable it. An unparseable value falls back to enabled. |
| `swingbridge.wheel.pixelsPerLine` | `40`                               | How many pixels of browser wheel delta count as one Swing line-scroll step, for browsers that report pixel deltas. The fractional remainder is carried per window so high-resolution wheels and trackpads scroll smoothly. A blank, non-numeric or non-positive value falls back to the default. Read once at startup.                                                                                                                                                                     |
| `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.                                                                                                                                                                                                                                                                      |

### <a id="swing-bridge.configuration.system-properties.logging"></a>Logging

See [Logging & Identifying Logs per User](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/logging.md#swing-bridge.logging) for the full picture, including the pattern-layout tokens.

| Property                           | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `swingbridge.consoleLogPrefix`     | `false` | When set to `true`, every console line written by an embedded Swing application is prefixed with that instance’s run ID (`[swing:<runId>]`), so concurrent users' output can be told apart in the server console.                                                                                                                                                                                                                                                                                                                                                              |
| `swingbridge.consoleLogMirrorFile` | —       | Path to a file that receives a copy of the prefixed console output, for when the server console itself is not retained.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `swingbridge.includeUserInLogs`    | `false` | When set to `true`, the logged-in user’s name is added to every attributed log line across all channels: the console prefix becomes `[swing:<runId>\|<user>]` and the `%swingUser` / `%X{swingUser}` pattern tokens render the name. Off by default because a user’s name is personal data; without it, the name appears only in the per-instance correlation line. Requires an identity to have been published. See [Showing the Name on Every Line](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/logging.md#swing-bridge.logging.identity.per-line). |
| `swingbridge.log.user`             | None    | Not set by the operator: an embedded Swing application sets this property at runtime, after its own login, to publish the authenticated user’s name for log attribution. The value is routed per session, so concurrent users can’t overwrite each other. See [Adding the User’s Name to the Logs](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/logging.md#swing-bridge.logging.identity).                                                                                                                                                             |

For Spring Boot, set system properties through `<systemPropertyVariables>` on the `spring-boot-maven-plugin` (see [Project Setup](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/installation-from-scratch.md#swing-bridge.installation-from-scratch.project-setup)) or pass `-D` flags on the command line. For a packaged JAR, pass them with `-D` on the command line:

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

## <a id="swing-bridge.configuration.jvm-tuning"></a>JVM Tuning for Multiple Sessions

SwingBridge runs every browser session’s Swing application inside one JVM, so the host’s garbage-collector settings decide how much memory a given number of concurrent sessions needs. The library cannot set these for you — they belong to the host application’s launch configuration, alongside the flags in [JVM Flags Reference](https://vaadin.com/docs/v25/tools/modernization-toolkit/swing-bridge/installation-from-scratch.md#swing-bridge.installation-from-scratch.jvm-flags).

The defaults are fine for a handful of sessions. The settings below matter when packing many sessions into one host.

| Flag                                             | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-XX:+UseStringDeduplication`                    | Concurrent sessions of the same application load the same strings repeatedly. G1’s string deduplication is close to free here and reduces the live set.                                                                                                                                                                                                                                                                                                                                 |
| `-XX:MinHeapFreeRatio=5 -XX:MaxHeapFreeRatio=20` | G1 as configured by default does not return a drained session’s heap to the operating system: committed heap grows and stays pinned, and an explicit `System.gc()` does not shrink it. These two ratios make G1 uncommit aggressively, which gives the tightest resident footprint of the collectors measured. The cost is more frequent collections; pauses stayed in the single-digit milliseconds, well inside one frame interval. Use `10`/`30` for a gentler throughput trade-off. |
| `-XX:+UseShenandoahGC`                           | An alternative when sessions are bursty and memory should come back promptly as they end: sub-millisecond pause times and prompt uncommit. Because it collects concurrently it needs allocation headroom, so budget close to `-Xmx` for the peak rather than the idle figure.                                                                                                                                                                                                           |

> **Caution:** ZGC is a poor fit for this workload. It has the highest peak footprint of the collectors measured and a large fixed metadata overhead, so its idle resident size lands **above** untuned G1 despite returning the most memory in absolute terms. It is a large-heap collector, and a host running many small Swing sessions is not that regime.

Which of these pays off depends on the Swing application and on how many sessions a host carries, so measure against your own application before adopting one as a default.

## <a id="swing-bridge.configuration.error-reporting"></a>Launch Failure Error View

When a Swing application embedded via `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](https://vaadin.com/privacy-policy) explaining how reports are processed.

### <a id="swing-bridge.configuration.error-reporting.disable"></a>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:

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

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