{"record":{"id":"82e5203ab06d14a5","repo":"java-native-access/jna","slug":"nested-structure-arrays-must-use-a-derived-structure-type-so","errorCode":null,"errorMessage":"Nested Structure arrays must use a derived Structure type so that the size of the elements can be determined","messagePattern":"Nested Structure arrays must use a derived Structure type so that the size of the elements can be determined","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Structure.java","lineNumber":1382,"sourceCode":"                // fields\n                field.setAccessible(true);\n            }\n            structField.field = field;\n            structField.name = field.getName();\n            structField.type = type;\n\n            // Check for illegal field types\n            if (Callback.class.isAssignableFrom(type) && !type.isInterface()) {\n                throw new IllegalArgumentException(\"Structure Callback field '\"\n                                                   + field.getName()\n                                                   + \"' must be an interface\");\n            }\n            if (type.isArray()\n                && Structure.class.equals(type.getComponentType())) {\n                String msg = \"Nested Structure arrays must use a \"\n                    + \"derived Structure type so that the size of \"\n                    + \"the elements can be determined\";\n                throw new IllegalArgumentException(msg);\n            }\n\n            int fieldAlignment = 1;\n            if (!Modifier.isPublic(field.getModifiers())) {\n                continue;\n            }\n\n            Object value = getFieldValue(structField.field);\n            if (value == null && type.isArray()) {\n                if (force) {\n                    throw new IllegalStateException(\"Array fields must be initialized\");\n                }\n                // can't calculate size yet, defer until later\n                return null;\n            }\n            Class<?> nativeType = type;\n            if (NativeMapped.class.isAssignableFrom(type)) {\n                NativeMappedConverter tc = NativeMappedConverter.getInstance(type);","sourceCodeStart":1364,"sourceCodeEnd":1400,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Structure.java#L1364-L1400","documentation":"A nested Structure array field must use a derived Structure type (a concrete subclass), not the abstract Structure base class, because JNA needs the concrete class to determine each element's native size. Declaring Structure[] is rejected with IllegalArgumentException.","triggerScenarios":"Declaring a field like public Structure[] items; where getComponentType() equals exactly Structure.class (not a subclass).","commonSituations":"Writing generic container structures without knowing concrete element types; converting C code with flexible arrays too literally; forgetting to define a concrete Structure subclass for the array elements.","solutions":["Define a concrete Structure subclass and declare the array with that type (e.g. public Point[] points)","If element sizes differ, model with Pointer plus manual reads, or several typed array fields","For unions of element types, pick a single concrete representative or use a union-based approach"],"exampleFix":"// before\nclass List extends Structure {\n    public Structure[] entries; // unknown element size\n}\n// after\nclass List extends Structure {\n    public Entry[] entries;\n}\nclass Entry extends Structure { public int id; }","handlingStrategy":"type-guard","validationCode":"for (Field f : S.class.getFields()) {\n    Class<?> t = f.getType();\n    if (t.isArray() && t.getComponentType() == Structure.class) {\n        throw new IllegalStateException(f + \" must use a derived Structure type\");\n    }\n}","typeGuard":"static boolean isValidArrayField(Class<?> t) {\n    return !t.isArray() || !Structure.class.equals(t.getComponentType());\n}","tryCatchPattern":"try {\n    s.size();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"Nested Structure arrays\")) {\n        throw new IllegalStateException(\"Use a concrete Structure subclass for array elements\", e);\n    }\n    throw e;\n}","preventionTips":["Always use concrete Structure subclasses for array element types","Never declare Structure[] fields","Model C flexible arrays with a max-size typed array plus explicit length","Unit-test size() of every structure"],"tags":["jna","structure","array","native-size"],"backgroundTag":"type-mismatch","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"}