{"record":{"id":"bb04b9a7a1d501da","repo":"java-native-access/jna","slug":"function-name-declared-structure-at-parameter-index-but-bb04b9","errorCode":null,"errorMessage":"Function <name> declared Structure[] at parameter <index> but element <i> is of Structure.ByReference type","messagePattern":"Function <name> declared Structure\\[\\] at parameter <index> but element <i> is of Structure\\.ByReference type","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Function.java","lineNumber":599,"sourceCode":"        } 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++) {\n                    pointers[i] = ss[i] != null ? ss[i].getPointer() : null;\n                }\n                return new PointerArray(pointers);\n            } else if (ss.length == 0) {\n                throw new IllegalArgumentException(\"Structure array must have non-zero length\");\n            } else if (ss[0] == null) {\n                Structure.newInstance((Class<? extends Structure>) type).toArray(ss);","sourceCodeStart":581,"sourceCodeEnd":617,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Function.java#L581-L617","documentation":"The inverse of error 326: if the mapping declares Structure[] by value, every element must NOT be a Structure.ByReference instance. A by-reference element in a by-value array is ambiguous for marshaling, so JNA rejects it at the specific offending index.","triggerScenarios":"Passing Structure[] where one or more elements were constructed as Structure.ByReference (directly or via newInstance of a ByReference subclass) while the function expects by-value structures.","commonSituations":"Mixing MyStruct and MyStruct.ByReference instances in one array after a refactor; auto-generated arrays that used ByReference for the element class.","solutions":["Create all array elements as the by-value class (e.g. new MyStruct(), not new MyStruct.ByReference())","If references are intended, change the mapping to Structure.ByReference[]","Use Structure.newInstance(byValueClass).toArray(ss) to populate arrays with correct element types"],"exampleFix":"// before\nMyStruct[] arr = { new MyStruct.ByReference() };\nf(arr);\n// after\nMyStruct[] arr = { new MyStruct() };\nf(arr);","handlingStrategy":"type-guard","validationCode":"for (int i = 0; i < ss.length; i++) {\n    if (ss[i] instanceof Structure.ByReference)\n        throw new IllegalStateException(\"by-value expected at element \" + i);\n}","typeGuard":"boolean isByValueArray(Structure[] ss) {\n    for (Structure s : ss) if (s instanceof Structure.ByReference) return false;\n    return true;\n}","tryCatchPattern":null,"preventionTips":["Never mix MyStruct and MyStruct.ByReference instances in one array","Populate structure arrays via newInstance(byValueClass).toArray() to guarantee element type"],"tags":["jna","structure","by-value","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"}