java-native-access/jna · error · X11Exception

Cannot get client list properties (_NET_CLIENT_LIST or _WIN_

Error message

Cannot get client list properties (_NET_CLIENT_LIST or _WIN_CLIENT_LIST)

What it means

X.getWindows() reads the list of managed client windows from the root window: first _NET_CLIENT_LIST (EWMH), falling back to _WIN_CLIENT_LIST. If both reads throw X11Exception, it throws X11Exception 'Cannot get client list properties (_NET_CLIENT_LIST or _WIN_CLIENT_LIST)'. The window manager is not publishing the client list this library relies on.

Source

Thrown at contrib/x11/src/jnacontrib/x11/api/X.java:209

        }

        /**
         * Returns all windows managed by the window manager.
         *
         * @return all windows managed by the window manager
         * @throws X11Exception thrown if X11 window errors occurred
         */
        public Window[] getWindows() throws X11Exception {
            byte[] bytes;
            Window rootWindow = getRootWindow();

            try {
                bytes = rootWindow.getProperty(X11.XA_WINDOW, "_NET_CLIENT_LIST");
            } catch (X11Exception e) {
                try {
                    bytes = rootWindow.getProperty(X11.XA_CARDINAL, "_WIN_CLIENT_LIST");
                } catch (X11Exception e1) {
                    throw new X11Exception("Cannot get client list properties (_NET_CLIENT_LIST or _WIN_CLIENT_LIST)");
                }
            }

            Window[] windowList = new Window[bytes.length / X11.Window.SIZE];

            for (int i = 0; i < windowList.length; i++) {
                windowList[i] = new Window(this, new X11.Window(bytesToInt(bytes, X11.XID.SIZE * i)));
            }

            return windowList;
        }

        /**
         * Returns the number of desktops.
         *
         * @return number of desktops
         * @throws X11Exception thrown if X11 window errors occurred
         */

View on GitHub (pinned to d036ad9781)

Solutions

Run an EWMH-compliant window manager on the X display (openbox, mutter, i3, etc.); verify with xprop -root _NET_CLIENT_LIST.
Wait for WM startup before calling getWindows (retry until properties appear).
For Wayland targets, use Wayland-native APIs or an XWayland session with an EWMH WM.
Catch X11Exception and return an empty window list when enumeration is optional.

Example fix

// before
X.Window[] windows = x.getWindows();
// after
try {
    X.Window[] windows = x.getWindows();
} catch (X11Exception e) {
    LOG.warn("No _NET_CLIENT_LIST/_WIN_CLIENT_LIST: is an EWMH WM running?");
    windows = new X.Window[0];
}

Defensive patterns

Strategy: try-catch

Validate before calling

// shell probe before calling the API
// xprop -root _NET_CLIENT_LIST  (non-empty => supported)

Try / catch

try {
    windows = x.getWindows();
} catch (X11Exception e) {
    windows = new X.Window[0]; // no client list available
}

Prevention

Run an EWMH-compliant WM; don't call getWindows on bare X/Xvfb without one.
Retry with backoff right after WM startup until properties exist.
Probe root-window properties with xprop before enabling window enumeration.
Return empty results instead of failing when window lists are optional.

When it happens

Trigger: Calling getWindows when the WM does not maintain _NET_CLIENT_LIST/_WIN_CLIENT_LIST on the root window, when no WM is running at all, or when the property atom/type read fails.

Common situations: Plain Xvfb or bare X with no WM, minimal/non-EWMH window managers, Wayland sessions, or querying too early before the WM initialized its properties.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of java-native-access/jna@d036ad9781 (2026-09-12). Data as JSON: /api/errors/1ff49c229f5c3cdc. Report an issue: GitHub.