xpipe-io/xpipe · warning · UnsupportedOperationException

SystemTray icons are not supported by the current desktop en

Error message

SystemTray icons are not supported by the current desktop environment.

What it means

Java's SystemTray API reports whether the current desktop environment supports tray icons. XPipe throws this UnsupportedOperationException from ensureSystemTraySupported when SystemTray.isSupported() is false, i.e. the environment offers no system tray (common on minimal Linux desktops, Wayland setups without tray protocols, or headless systems).

Source

Thrown at app/src/main/java/io/xpipe/app/core/AppTrayIcon.java:90

            if (OsType.ofLocal() != OsType.MACOS) {
                tray.remove(trayIcon);
                AppOperationMode.switchToAsync(AppOperationMode.GUI);
            }
        });
    }

    private static Image loadImageFromURL(URL iconImagePath) {
        try {
            return ImageIO.read(iconImagePath);
        } catch (IOException e) {
            ErrorEventFactory.fromThrowable(e).handle();
            return AppImages.toAwtImage(AppImages.DEFAULT_IMAGE);
        }
    }

    private void ensureSystemTraySupported() {
        if (!SystemTray.isSupported()) {
            throw new UnsupportedOperationException(
                    "SystemTray icons are not " + "supported by the current desktop environment.");
        }
    }

    public void show() {
        EventQueue.invokeLater(() -> {
            try {
                tray.add(this.trayIcon);
            } catch (Exception e) {
                // This can sometimes fail on Linux
                ErrorEventFactory.fromThrowable("Unable to add TrayIcon", e)
                        .expected()
                        .handle();
            }
        });
    }

    public void hide() {

View on GitHub (pinned to d85ca821ba)

Solutions

1. Disable the tray icon feature in XPipe settings so AppTrayIcon is never created
2. Run under a desktop environment that provides a system tray (or add a tray provider applet)
3. If embedding, guard creation with SystemTray.isSupported() before instantiating AppTrayIcon

Example fix

// before
var tray = new AppTrayIcon();
// after
if (SystemTray.isSupported()) {
    var tray = new AppTrayIcon();
} else {
    // fall back to no tray behavior
}

if (!java.awt.SystemTray.isSupported()) {
    // skip tray setup
}

boolean trayAvailable() { return java.awt.SystemTray.isSupported(); }

try { new AppTrayIcon().show(); } catch (UnsupportedOperationException e) { /* proceed without tray icon */ }

When it happens

Trigger: Constructing AppTrayIcon (constructor calls ensureSystemTraySupported) on a desktop environment where java.awt.SystemTray.isSupported() returns false.

Common situations: Running on a Linux WM without a freedesktop StatusNotifier/system tray; headless server or CI with a DISPLAY but no tray; some Wayland compositors; remote desktop sessions.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

AI-assisted analysis of xpipe-io/xpipe@d85ca821ba (2026-09-06). Data as JSON: /api/errors/842b14678b654a1a. Report an issue: GitHub.