{"record":{"id":"891746339c2fa604","repo":"xpipe-io/xpipe","slug":"failed-to-load-graphics-support-please-note-that","errorCode":null,"errorMessage":"Failed to load graphics support\n\nPlease note that XPipe is a desktop application that should be run on your local workstation. It is able to provide the full functionality for all integrations via remote server connections, e.g. via SSH.","messagePattern":"Failed to load graphics support\n\nPlease note that XPipe is a desktop application that should be run on your local workstation\\. It is able to provide the full functionality for all integrations via remote server connections, e\\.g\\. via SSH\\.","errorType":"exception","errorClass":"Throwable","httpStatus":null,"severity":"critical","filePath":"app/src/main/java/io/xpipe/app/platform/PlatformState.java","lineNumber":63,"sourceCode":"    public static void teardown() {\n        if (current != RUNNING) {\n            return;\n        }\n\n        setCurrent(PlatformState.EXITED);\n\n        // Give other threads, e.g. windows shutdown hook time to properly signal exit state\n        ThreadHelper.sleep(100);\n\n        Platform.exit();\n    }\n\n    public static void initPlatformOrThrow() throws Throwable {\n        if (current == NOT_INITIALIZED) {\n            PlatformState.initPlatform();\n        }\n        if (lastError != null) {\n            throw getLastError();\n        }\n    }\n\n    private static String getErrorMessage(String message) {\n        var header = message != null ? message + \"\\n\\n\" : \"Failed to load graphics support\\n\\n\";\n        var msg =\n                header + \"Please note that XPipe is a desktop application that should be run on your local workstation.\"\n                        + \" It is able to provide the full functionality for all integrations via remote server connections, e.g. via SSH.\"\n                        + \" You don't have to install XPipe on any system like a server, a WSL distribution, a hypervisor, etc.,\"\n                        + \" to have full access to that system, a shell connection to it is enough for XPipe to work from your local machine.\";\n        return msg;\n    }\n\n    public static void handleStderrMessage(String msg) {\n        if (restartQueued) {\n            return;\n        }\n","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/xpipe-io/xpipe/blob/d85ca821baa46092a320ebb13546d7240adb74f8/app/src/main/java/io/xpipe/app/platform/PlatformState.java#L45-L81","documentation":"PlatformState.initPlatformOrThrow() initializes the JavaFX/graphics platform; if initialization fails, lastError holds a PlatformState init failure whose message defaults to \"Failed to load graphics support\" plus guidance that XPipe is a desktop application and remote connections should be used for integrations. getErrorMessage() appends the header when no specific message exists.","triggerScenarios":"Calling initPlatformOrThrow() (during app startup) on a machine without a display/graphics environment: headless server, missing X11/Wayland display, missing libgtk/libgl libraries, or running in a container/SSH session without display forwarding.","commonSituations":"Running XPipe on a headless Linux server; DISPLAY unset or X server not reachable; missing GTK/JavaFX native deps; Windows/WSL without WSLg; CI/container environments; broken GPU drivers.","solutions":["Run XPipe on a machine with a working desktop environment (local workstation)","On headless Linux, set up X11 forwarding (ssh -X) or access the machine via XPipe from a desktop instead","Install missing graphics libraries (libgtk-3, libgl1, fontconfig) or set DISPLAY correctly","Check lastError / getLastError() message for the exact underlying graphics initialization failure"],"exampleFix":"// before (headless)\n$ ./xpipe.sh  # Failed to load graphics support\n// after (with display)\n$ export DISPLAY=:0  # or ssh -X into the machine from a desktop\n$ ./xpipe.sh","handlingStrategy":"try-catch","validationCode":"if (java.awt.GraphicsEnvironment.isHeadless()) {\n    // warn: XPipe desktop UI cannot start on this machine\n}","typeGuard":null,"tryCatchPattern":"try {\n    PlatformState.initPlatformOrThrow();\n} catch (Throwable t) {\n    // inspect message for graphics support guidance; run on a desktop instead\n}","preventionTips":["Run XPipe only on machines with a display server (X11/Wayland/Windows desktop)","Install GTK/GL/font libraries before launch on Linux","Use SSH connections from a desktop XPipe install rather than running it headless","Verify DISPLAY is set when launching from scripts/CI"],"tags":["javafx","graphics","headless","startup","platform"],"backgroundTag":"unsupported-platform","analyzedSha":"d85ca821baa46092a320ebb13546d7240adb74f8","analyzedAt":"2026-09-06T14:30:08.251Z","contentChangedAt":"2026-09-06T14:30:08.251Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}