#Can't connect to X11 using ':99'

#Expected Behavior

Application starts normally.

#Actual Behavior

The application fails to start. The browser may remain on the startup screen or report a startup error.

#Exception

java.awt.AWTError: Can't connect to X11 window server using ':99' as the value of the DISPLAY variable.

#Steps to Reproduce the Problem

1. Install Webswing on Linux
2. Start Webswing
3. Start any application through browser

#Solution

Check the display configuration of the standalone server or the Session Pool that launches the application.

• To use built-in XHeadless: leave DISPLAY unset and keep webswing.xheadless.enabled=true (the default). Restart the server or Session Pool after changing its configuration. The start command automatically uses xvfb-run when it is available and no external display is configured. The foreground run command does not start Xvfb. To use built-in XHeadless even with Xvfb installed, use run or the direct Java systemd service without DISPLAY.
• To use an external display: verify that DISPLAY points to a running X server and that the Webswing service account has access, including the required Xauthority credentials. A stale local display or incorrect remote address can prevent automatic fallback.
• If xvfb-run fails before Webswing starts: check that xvfb-run and xauth are installed and the selected display number is available. Check the startup log even if the script prints STARTED.
• If a custom launcher starts applications in another container or network environment: provide a display reachable from that environment.

Review the server or Session Pool log for the original connection error before retrying the application. Native X11 features that require a full X server need Xvfb or another external display.

See XHeadless setup and configuration.