{"record":{"id":"11bbc0f2baeb8b59","repo":"java-native-access/jna","slug":"array-fields-must-be-initialized","errorCode":null,"errorMessage":"Array fields must be initialized","messagePattern":"Array fields must be initialized","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Structure.java","lineNumber":1393,"sourceCode":"                                                   + \"' 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);\n                nativeType = tc.nativeType();\n                structField.writeConverter = tc;\n                structField.readConverter = tc;\n                structField.context = new StructureReadContext(this, field);\n            }\n            else if (typeMapper != null) {\n                ToNativeConverter writeConverter = typeMapper.getToNativeConverter(type);\n                FromNativeConverter readConverter = typeMapper.getFromNativeConverter(type);\n                if (writeConverter != null && readConverter != null) {\n                    value = writeConverter.toNative(value,\n                                                    new StructureWriteContext(this, structField.field));","sourceCodeStart":1375,"sourceCodeEnd":1411,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Structure.java#L1375-L1411","documentation":"During size calculation with force=true, a Structure array field that is still null means JNA cannot determine the array length, so the structure's size is unknown. IllegalStateException 'Array fields must be initialized' is thrown instead of deferring the calculation.","triggerScenarios":"Calling size()/getNativeSize/calculations that force layout while an array field remains null (never assigned), e.g. invoking size(true) or methods that force calculation before initializing array fields.","commonSituations":"Constructing a Structure and computing its size before assigning array fields; arrays initialized lazily in a constructor that wasn't run; serialization/deserialization flows that leave arrays null; getFieldValue returning null due to access problems.","solutions":["Assign every array field a non-null, correctly sized array before calling size()/write()","Call allocateMemory()/ensureAllocated only after array initialization, or initialize fields in the constructor","Use initializeField semantics: set defaults for all array fields in the Structure's no-arg constructor","If arrays are dynamic, reserve a maximum size and track the used length separately"],"exampleFix":"// before\nclass Buf extends Structure {\n    public byte[] data;\n}\nBuf b = new Buf();\nb.size(); // data is null\n// after\nclass Buf extends Structure {\n    public byte[] data = new byte[64];\n}","handlingStrategy":"validation","validationCode":"for (Field f : S.class.getFields()) {\n    if (f.getType().isArray()) {\n        f.setAccessible(true);\n        try { if (f.get(s) == null) throw new IllegalStateException(\"Null array field: \" + f); }\n        catch (IllegalAccessException e) { throw new IllegalStateException(e); }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    s.size();\n} catch (IllegalStateException e) {\n    if (\"Array fields must be initialized\".equals(e.getMessage())) {\n        s.setData(new byte[expectedLen]); // initialize then retry\n        s.size();\n    } else throw e;\n}","preventionTips":["Initialize all array fields eagerly in the constructor","Never call size()/write() before arrays are assigned","Give arrays fixed maximum sizes and track logical length separately","Add constructor-time assertions for non-null arrays"],"tags":["jna","structure","array","null","initialization"],"backgroundTag":"empty-required-field","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"}