{"record":{"id":"3dfb9997af5ddb39","repo":"java-native-access/jna","slug":"invalid-return-format","errorCode":null,"errorMessage":"Invalid return format","messagePattern":"Invalid return format","errorType":"exception","errorClass":"X11Exception","httpStatus":null,"severity":"error","filePath":"contrib/x11/src/jnacontrib/x11/api/X.java","lineNumber":1060,"sourceCode":"                String prop_name = x11.XGetAtomName(display.x11Display, xa_prop_name);\n                throw new X11Exception(\"Invalid type of \" + prop_name + \" property\");\n            }\n\n            int ret_format = ret_format_ref.getValue();\n            long ret_nitems = ret_nitems_ref.getValue().longValue();\n\n            // null terminate the result to make string handling easier\n            int nbytes;\n            if (ret_format == 32)\n                nbytes = Native.LONG_SIZE;\n            else if (ret_format == 16)\n                nbytes = Native.LONG_SIZE / 2;\n            else if (ret_format == 8)\n                nbytes = 1;\n            else if (ret_format == 0)\n                nbytes = 0;\n            else\n                throw new X11Exception(\"Invalid return format\");\n            int length = Math.min((int) ret_nitems * nbytes, MAX_PROPERTY_VALUE_LEN);\n\n            byte[] ret = ret_prop.getByteArray(0, length);\n\n            x11.XFree(ret_prop);\n            return ret;\n        }\n\n        /**\n         * Returns the property value as a byte array.\n         *\n         * @param xa_prop_type property type\n         * @param xa_prop_name property name\n         * @return property value as a byte array\n         * @throws X11Exception thrown if X11 window errors occurred\n         */\n        public byte[] getProperty(X11.Atom xa_prop_type, String xa_prop_name) throws X11Exception {\n            return getProperty(xa_prop_type, display.getAtom(xa_prop_name));","sourceCodeStart":1042,"sourceCodeEnd":1078,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/contrib/x11/src/jnacontrib/x11/api/X.java#L1042-L1078","documentation":"Window.getProperty validates the format field returned by XGetWindowProperty. Only 32, 16, 8 and 0 bits-per-unit are handled (mapped to sizes via Native.LONG_SIZE); any other format value triggers \"Invalid return format\". This indicates a protocol-level anomaly or corrupted/unsupported property reply.","triggerScenarios":"XGetWindowProperty replying with a format value outside {32,16,8,0} — effectively never from a conforming X server, so typically it signals misuse of the library or a broken X server/serialization bug.","commonSituations":"Buggy or nonstandard X servers/proxies (e.g. some VNC or nested-X implementations), memory corruption in the reply when mixing JNA struct versions, or reading a property whose definition changed between X protocol revisions.","solutions":["Update JNA and the x11contrib bindings to current versions","Test against a standard X server (Xorg/Xvfb) to isolate proxy/nested-server quirks","Catch X11Exception around property reads and fall back to another property source","If persistent, dump the raw reply with xprop and compare formats to confirm server misbehavior"],"exampleFix":"// before\nbyte[] data = win.getProperty(type, name); // throws on odd format\n// after\nbyte[] data;\ntry {\n    data = win.getProperty(type, name);\n} catch (X11Exception e) {\n    if (!e.getMessage().contains(\"Invalid return format\")) throw e;\n    data = new byte[0];\n}","handlingStrategy":"retry","validationCode":"// standard X server sanity check before bulk property reads\nProcess p = Runtime.getRuntime().exec(new String[]{\"xdpyinfo\",\"-display\",System.getenv(\"DISPLAY\")});\nboolean healthy = p.waitFor() == 0;","typeGuard":null,"tryCatchPattern":"try {\n    data = win.getProperty(type, atom);\n} catch (X11Exception e) {\n    if (e.getMessage().contains(\"Invalid return format\")) {\n        data = retryOnceOrEmpty(); // suspect nonstandard server/proxy\n    } else throw e;\n}","preventionTips":["Test against Xorg/Xvfb, not exotic nested/VNC X servers","Keep JNA and bindings versions current","Log the property name and format when this fires for diagnosis","Wrap property reads so protocol anomalies degrade gracefully"],"tags":["x11","xgetwindowproperty","format","protocol"],"backgroundTag":"unexpected-response-shape","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}