java-native-access/jna · error · X11Exception

Cannot get property.

Error message

Cannot get <prop_name> property.

What it means

Window.getProperty is the core XGetWindowProperty wrapper. When the X call itself fails (return code != Success), the method resolves the property atom's name via XGetAtomName and throws this X11Exception naming the property whose value could not be retrieved.

Solutions

1. Verify the atom exists with xprop or xwininfo -tree before querying
2. Re-fetch the window handle; the target window may have been destroyed
3. Use XInternAtom to confirm the atom name is spelled correctly (case-sensitive)
4. Catch X11Exception per property so a missing optional property doesn't abort the whole flow

Example fix

// before
String name = win.getStringProperty(x11.XInternAtom(display, "_NET_WM_NAME", false));
// after
String name;
try {
    name = win.getStringProperty(x11.XInternAtom(display, "_NET_WM_NAME", false));
} catch (X11Exception e) {
    name = ""; // property unavailable on this window
}

// confirm the property exists on the window before reading
Process p = Runtime.getRuntime().exec(new String[]{"xprop","-id", String.valueOf(winid), propName});
boolean exists = p.waitFor() == 0;

try {
    value = win.getStringProperty(atom);
} catch (X11Exception e) {
    if (e.getMessage().contains("Cannot get")) {
        value = null; // property not present on this window
    } else {
        throw e;
    }
}

When it happens

Trigger: Any property read (getIntProperty, getStringProperty, getUtf8ListProperty, etc.) where XGetWindowProperty returns a non-Success status: bad window handle, invalid/unknown atom, or X connection errors.

Common situations: Querying a property atom that doesn't exist on the target window, using a stale Window/x11Window id after the window was closed, or an X server that has dropped the connection.

Related errors

• Invalid return format
• Invalid type of property
• Attempting to retrieve VisualID from a null Visual
• Can't open X Display
• Can't open X Display

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

Appendix: source

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

            X11.AtomByReference xa_ret_type_ref = new X11.AtomByReference();
            IntByReference ret_format_ref = new IntByReference();
            NativeLongByReference ret_nitems_ref = new NativeLongByReference();
            NativeLongByReference ret_bytes_after_ref = new NativeLongByReference();
            PointerByReference ret_prop_ref = new PointerByReference();

            NativeLong long_offset = new NativeLong(0);
            NativeLong long_length = new NativeLong(MAX_PROPERTY_VALUE_LEN / 4);

            /* MAX_PROPERTY_VALUE_LEN / 4 explanation (XGetWindowProperty manpage):
             *
             * long_length = Specifies the length in 32-bit multiples of the
             *               data to be retrieved.
             */
            if (x11.XGetWindowProperty(display.x11Display, x11Window, xa_prop_name, long_offset, long_length, false,
                    xa_prop_type, xa_ret_type_ref, ret_format_ref,
                    ret_nitems_ref, ret_bytes_after_ref, ret_prop_ref) != X11.Success) {
                String prop_name = x11.XGetAtomName(display.x11Display, xa_prop_name);
                throw new X11Exception("Cannot get " + prop_name + " property.");
            }

            X11.Atom xa_ret_type = xa_ret_type_ref.getValue();
            Pointer ret_prop = ret_prop_ref.getValue();

            if (xa_ret_type == null) {
                //the specified property does not exist for the specified window
                return null;
            }

            if( xa_ret_type == null ){
                //the specified property does not exist for the specified window
                return null;
            }

            if( xa_ret_type == null ){
                //the specified property does not exist for the specified window
                return null;

View on GitHub (pinned to d036ad9781)