{"record":{"id":"272f44331c4ea795","repo":"java-native-access/jna","slug":"structure-field-structfield-name-was-declared-as-structfield","errorCode":null,"errorMessage":"Structure field \\\"\" + structField.name + \"\\\" was declared as \" + structField.type + (structField.type == fieldType ? \"\" : \" (native type \" + fieldType + \")\") + \", which is not supported within a Structure\"","messagePattern":"Structure field \\\\\"\" \\+ structField\\.name \\+ \"\\\\\" was declared as \" \\+ structField\\.type \\+ \\(structField\\.type == fieldType \\? \"\" : \" \\(native type \" \\+ fieldType \\+ \"\\)\"\\) \\+ \", which is not supported within a Structure\"","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Structure.java","lineNumber":913,"sourceCode":"                // value is changed, keep the new native string alive\n                current.peer = nativeString;\n                value = nativeString.getPointer();\n            }\n            else {\n                nativeStrings.remove(structField.name);\n            }\n        }\n\n        try {\n            memory.setValue(offset, value, fieldType);\n        }\n        catch(IllegalArgumentException e) {\n            String msg = \"Structure field \\\"\" + structField.name\n                + \"\\\" was declared as \" + structField.type\n                + (structField.type == fieldType\n                   ? \"\" : \" (native type \" + fieldType + \")\")\n                + \", which is not supported within a Structure\";\n            throw new IllegalArgumentException(msg, e);\n        }\n    }\n\n    /** Used to declare fields order as metadata instead of method.\n     * example:\n     * <pre><code>\n     * // New\n     * {@literal @}FieldOrder({ \"n\", \"s\" })\n     * class Parent extends Structure {\n     *     public int n;\n     *     public String s;\n     * }\n     * {@literal @}FieldOrder({ \"d\", \"c\" })\n     * class Son extends Parent {\n     *     public double d;\n     *     public char c;\n     * }\n     * // Old","sourceCodeStart":895,"sourceCodeEnd":931,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Structure.java#L895-L931","documentation":"When JNA validates or marshals a structure field, an inner IllegalArgumentException from the type conversion is rethrown with a message naming the field, its declared Java type, and the attempted native type, explaining that the combination is not supported within a Structure. JNA only supports a fixed set of Java types in structure layouts.","triggerScenarios":"Declaring a Structure field of an unmapped type (e.g. boolean is supported, but arbitrary POJOs, boxed types not in the supported set, String without proper marshaling hints, arrays of unsupported element types, or a nested object that is neither Structure nor NativeMapped); passing an incompatible native type via a TypeMapper/NativeMapped conversion that itself throws IllegalArgumentException.","commonSituations":"Custom classes used as fields without implementing NativeMapped or having a TypeMapper; using Integer/Long wrappers instead of primitives in old JNA versions; forgetting to register a TypeMapper on the structure or library; arrays sized incorrectly.","solutions":["Change the field type to a JNA-supported type (primitives, Pointer, String, WString, Buffer, arrays of primitives, nested Structure, Callback, NativeLong, etc.)","Implement NativeMapped on the custom class, or register a TypeMapper via TypeMapper/mapper argument so the type can be converted","Check the wrapped cause (the original IllegalArgumentException) for the exact conversion failure","If using generics/boxed types, replace with the corresponding primitive or JNA numeric wrapper class intended for native sizes"],"exampleFix":"// before\nclass Cfg extends Structure {\n    public MyStatus status; // unsupported POJO\n}\n// after\nclass Cfg extends Structure {\n    public int status; // or implement NativeMapped on MyStatus\n}","handlingStrategy":"validation","validationCode":"static boolean isJnaFieldType(java.lang.Class<?> t) {\n    return t.isPrimitive() || com.sun.jna.Pointer.class.isAssignableFrom(t)\n        || t == String.class || t == com.sun.jna.WString.class\n        || com.sun.jna.Structure.class.isAssignableFrom(t)\n        || com.sun.jna.Callback.class.isAssignableFrom(t)\n        || com.sun.jna.NativeMapped.class.isAssignableFrom(t)\n        || (t.isArray() && isJnaFieldType(t.getComponentType()));\n}","typeGuard":"if (!isJnaFieldType(field.getType()) && mapper == null) {\n    throw new IllegalArgumentException(\"Unsupported structure field type: \" + field.getType());\n}","tryCatchPattern":"try { struct.write(); } catch (IllegalArgumentException e) { /* unsupported field type: inspect e.getMessage() for field name */ }","preventionTips":["Only use documented JNA-supported field types","Implement NativeMapped or a TypeMapper for custom classes","Use primitives, not boxed types, for numeric fields","Unit-test every Structure by calling write()/read() early"],"tags":["jna","structure","type-mismatch","marshaling"],"backgroundTag":"unsupported-dtype","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"}