{"record":{"id":"9442647fd68311b0","repo":"java-native-access/jna","slug":"function-name-declared-structure-at-parameter-index-but","errorCode":null,"errorMessage":"Function <name> declared Structure[] at parameter <index> but array of <type> was passed","messagePattern":"Function <name> declared Structure\\[\\] at parameter <index> but array of <type> was passed","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Function.java","lineNumber":592,"sourceCode":"            return Boolean.TRUE.equals(arg) ? INTEGER_TRUE : INTEGER_FALSE;\n        } else if (String[].class == argClass) {\n            return new StringArray((String[])arg, encoding);\n        } else if (WString[].class == argClass) {\n            return new StringArray((WString[])arg);\n        } else if (Pointer[].class == argClass) {\n            return new PointerArray((Pointer[])arg);\n        } else if (NativeMapped[].class.isAssignableFrom(argClass)) {\n            return new NativeMappedArray((NativeMapped[])arg);\n        } else if (Structure[].class.isAssignableFrom(argClass)) {\n            // If the signature is Structure[], disallow\n            // Structure.ByReference[] and Structure.ByReference elements\n            Structure[] ss = (Structure[])arg;\n            Class<?> type = argClass.getComponentType();\n            boolean byRef = Structure.ByReference.class.isAssignableFrom(type);\n            if (expectedType != null) {\n                if (!Structure.ByReference[].class.isAssignableFrom(expectedType)) {\n                    if (byRef) {\n                        throw new IllegalArgumentException(\"Function \" + getName()\n                                                           + \" declared Structure[] at parameter \"\n                                                           + index + \" but array of \"\n                                                           + type + \" was passed\");\n                    }\n                    for (int i=0;i < ss.length;i++) {\n                        if (ss[i] instanceof Structure.ByReference) {\n                            throw new IllegalArgumentException(\"Function \" + getName()\n                                                               + \" declared Structure[] at parameter \"\n                                                               + index + \" but element \" + i\n                                                               + \" is of Structure.ByReference type\");\n                        }\n                    }\n                }\n            }\n            if (byRef) {\n                Structure.autoWrite(ss);\n                Pointer[] pointers = new Pointer[ss.length + 1];\n                for (int i=0;i < ss.length;i++) {","sourceCodeStart":574,"sourceCodeEnd":610,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Function.java#L574-L610","documentation":"When a mapped function expects Structure.ByReference[] (an array of pointers to structures) but the caller passed an array whose component type is a by-value Structure subclass, JNA throws IllegalArgumentException because it cannot safely reinterpret by-value elements as by-reference.","triggerScenarios":"Calling a native function whose Java mapping declares Structure.ByReference[] (or an expectedType that is ByReference[]) while passing Structure[] where elements are by-value structures (not ByReference).","commonSituations":"Refactoring a struct array parameter from by-value to by-reference without updating call sites; mixing Structure and Structure.ByReference subclasses in the same codebase.","solutions":["Change the argument to a Structure.ByReference[] (construct elements as ByReference instances)","Or change the mapping's expected parameter type to Structure[] if the native API takes the array by value","Ensure consistent ByReference annotations across the interface and call sites"],"exampleFix":"// before\nMyStruct[] arr = { new MyStruct() }; // by value\nf(arr);\n// after\nMyStruct.ByReference[] arr = { new MyStruct.ByReference() };\nf(arr);","handlingStrategy":"type-guard","validationCode":"if (expectedType != null && Structure.ByReference[].class.isAssignableFrom(expectedType)) {\n    for (Structure s : ss) {\n        if (!(s instanceof Structure.ByReference)) throw new IllegalStateException(\"need ByReference elements\");\n    }\n}","typeGuard":"boolean isByRefArray(Structure[] ss) {\n    return ss.length == 0 || ss[0] instanceof Structure.ByReference;\n}","tryCatchPattern":null,"preventionTips":["Match the array element class to the mapping (ByReference[] needs ByReference elements)","Keep one canonical element class per struct binding and construct arrays only from it"],"tags":["jna","structure","by-reference","illegal-argument"],"backgroundTag":"incompatible-source-type","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"}