{"record":{"id":"1ff49c229f5c3cdc","repo":"java-native-access/jna","slug":"cannot-get-client-list-properties-net-client-list-or-win","errorCode":null,"errorMessage":"Cannot get client list properties (_NET_CLIENT_LIST or _WIN_CLIENT_LIST)","messagePattern":"Cannot get client list properties \\(_NET_CLIENT_LIST or _WIN_CLIENT_LIST\\)","errorType":"exception","errorClass":"X11Exception","httpStatus":null,"severity":"error","filePath":"contrib/x11/src/jnacontrib/x11/api/X.java","lineNumber":209,"sourceCode":"        }\n\n        /**\n         * Returns all windows managed by the window manager.\n         *\n         * @return all windows managed by the window manager\n         * @throws X11Exception thrown if X11 window errors occurred\n         */\n        public Window[] getWindows() throws X11Exception {\n            byte[] bytes;\n            Window rootWindow = getRootWindow();\n\n            try {\n                bytes = rootWindow.getProperty(X11.XA_WINDOW, \"_NET_CLIENT_LIST\");\n            } catch (X11Exception e) {\n                try {\n                    bytes = rootWindow.getProperty(X11.XA_CARDINAL, \"_WIN_CLIENT_LIST\");\n                } catch (X11Exception e1) {\n                    throw new X11Exception(\"Cannot get client list properties (_NET_CLIENT_LIST or _WIN_CLIENT_LIST)\");\n                }\n            }\n\n            Window[] windowList = new Window[bytes.length / X11.Window.SIZE];\n\n            for (int i = 0; i < windowList.length; i++) {\n                windowList[i] = new Window(this, new X11.Window(bytesToInt(bytes, X11.XID.SIZE * i)));\n            }\n\n            return windowList;\n        }\n\n        /**\n         * Returns the number of desktops.\n         *\n         * @return number of desktops\n         * @throws X11Exception thrown if X11 window errors occurred\n         */","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/x11/src/jnacontrib/x11/api/X.java#L191-L227","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nX.Window[] windows = x.getWindows();\n// after\ntry {\n    X.Window[] windows = x.getWindows();\n} catch (X11Exception e) {\n    LOG.warn(\"No _NET_CLIENT_LIST/_WIN_CLIENT_LIST: is an EWMH WM running?\");\n    windows = new X.Window[0];\n}","handlingStrategy":"try-catch","validationCode":"// shell probe before calling the API\n// xprop -root _NET_CLIENT_LIST  (non-empty => supported)","typeGuard":null,"tryCatchPattern":"try {\n    windows = x.getWindows();\n} catch (X11Exception e) {\n    windows = new X.Window[0]; // no client list available\n}","preventionTips":["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."],"tags":["x11","window-manager","ewmh","linux"],"backgroundTag":"resource-not-found","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}