{"record":{"id":"73ad5539649bea80","repo":"java-native-access/jna","slug":"this-pointer-is-opaque","errorCode":null,"errorMessage":"This pointer is opaque: ","messagePattern":"This pointer is opaque: ","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Pointer.java","lineNumber":1260,"sourceCode":"        @Override\n        public void read(long bOff, Pointer[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, byte[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, char[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, short[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, int[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, long[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, float[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, double[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override\n        public void write(long bOff, Pointer[] buf, int index, int length) {\n            throw new UnsupportedOperationException(MSG);\n        }\n        @Override","sourceCodeStart":1242,"sourceCodeEnd":1278,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Pointer.java#L1242-L1278","documentation":"JNA's Pointer.Opaque throws UnsupportedOperationException with the message \"This pointer is opaque: \" + this for every memory operation. This entry is the short[] write overload: opaque memory must not be mutated.","triggerScenarios":"Calling Pointer.write(long bOff, short[] buf, int index, int length) on a Pointer.Opaque instance.","commonSituations":"Filling short arrays (e.g. audio samples, 16-bit data) through a handle obtained from Pointer.createOpaque or an opaque native return value.","solutions":["Do not write via the opaque pointer; use it only to identify the native object.","Allocate a Memory buffer, write the short[] there, and pass it to a native function.","Check the pointer for opacity before writing.","Expose a native setter (e.g. void set(Handle, short*, int)) and call it with the handle."],"exampleFix":"// before\nPointer opaque = lib.getHandle();\nopaque.write(0, new short[]{1, 2}, 0, 2); // throws\n\n// after\nMemory mem = new Memory(4);\nmem.write(0, new short[]{1, 2}, 0, 2);\nlib.setHandleShorts(opaque, mem, 2);","handlingStrategy":"try-catch","validationCode":"if (p == null || p.toString().startsWith(\"opaque@\")) {\n    throw new IllegalArgumentException(\"cannot write short[] to opaque pointer\");\n}","typeGuard":"public static boolean supportsWrite(Pointer p) {\n    return p != null && !p.toString().startsWith(\"opaque@\");\n}","tryCatchPattern":"try {\n    p.write(bOff, buf, 0, len);\n} catch (UnsupportedOperationException e) {\n    if (String.valueOf(e.getMessage()).contains(\"opaque\")) {\n        Memory mem = new Memory((long) len * 2);\n        mem.write(0, buf, 0, len);\n        nativeSetShorts(handle, mem, len);\n        return;\n    }\n    throw e;\n}","preventionTips":["Allocate Memory for buffer writes; never mutate handles.","Guard all write helpers with an opacity check.","Treat native-returned handles as immutable identifiers.","Write integration tests that call every native accessor to surface opaque returns early."],"tags":["jna","native-memory","opaque-pointer","unsupported-operation"],"backgroundTag":"unsupported-operation","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"}