{"record":{"id":"f3aebabe735c80c3","repo":"java-native-access/jna","slug":"jna-failed-to-create-structure","errorCode":null,"errorMessage":"JNA: failed to create structure\n","messagePattern":"JNA: failed to create structure\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"native/dispatch.c","lineNumber":974,"sourceCode":"}\n\njobject\nnewJavaPointer(JNIEnv *env, void *p)\n{\n    jobject obj = NULL;\n    if (p != NULL) {\n      obj = (*env)->NewObject(env, classPointer, MID_Pointer_init, A2L(p));\n    }\n    return obj;\n}\n\njobject\nnewJavaStructure(JNIEnv *env, void *data, jclass type)\n{\n  if (data != NULL) {\n    volatile jobject obj = (*env)->CallStaticObjectMethod(env, classStructure, MID_Structure_newInstance, type, A2L(data));\n    if (obj == NULL) {\n      fprintf(stderr, \"JNA: failed to create structure\\n\");\n    }\n    return obj;\n  }\n  return NULL;\n}\n\njobject\nnewJavaCallback(JNIEnv* env, void* fptr, jclass type)\n{\n  if (fptr != NULL) {\n    jobject ptr = newJavaPointer(env, fptr);\n    return (*env)->CallStaticObjectMethod(env, classCallbackReference,\n                                          MID_CallbackReference_getCallback,\n                                          type, ptr, JNI_TRUE);\n  }\n  return NULL;\n}\n","sourceCodeStart":956,"sourceCodeEnd":992,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/native/dispatch.c#L956-L992","documentation":"newJavaStructure instantiates a Java Structure object from native memory by reflectively calling Structure.newInstance via JNI. If the constructor returns NULL (instantiation failed and a pending JNI exception exists), JNA prints this message and returns null to the caller. The Structure will be missing wherever this native pointer was expected.","triggerScenarios":"CallStaticObjectMethod(Structure.newInstance) returns NULL — the Structure subclass has no accessible no-arg constructor, its constructor throws, the class fails to initialize, or the JVM is out of memory.","commonSituations":"Structure classes defined as non-static inner classes (no implicit no-arg ctor), Structure subclass constructor throwing during field init, structures returned inside callbacks or nested structure reads, obfuscated/proguarded classes stripped of constructors.","solutions":["Ensure the Structure subclass is a static (or top-level) class with a public no-argument constructor.","Check stderr/heap dump for the original JNI exception (NoSuchMethodException/InvocationTargetException) raised before this message.","Keep-keep rules: exclude JNA Structure classes from ProGuard/R8 shrinking.","Verify the field/return type declared in the mapping actually matches the Structure class being constructed."],"exampleFix":"// before\nclass Outer { class Point extends Structure { ... } } // inner class, no no-arg ctor\n// after\nclass Outer { public static class Point extends Structure { public Point() {} ... } }","handlingStrategy":"type-guard","validationCode":"// Before passing a Structure subclass to a mapping, verify construction:\ntry {\n  Class<?> c = structClass;\n  if (c.isMemberClass() && !java.lang.reflect.Modifier.isStatic(c.getModifiers()))\n      throw new IllegalArgumentException(\"Structure must be static/top-level\");\n  c.getDeclaredConstructor().setAccessible(true);\n} catch (NoSuchMethodException e) { /* fix class: add public no-arg ctor */ }","typeGuard":"static boolean isInstantiableStructure(Class<?> c) {\n  if (!Structure.class.isAssignableFrom(c)) return false;\n  if (c.isMemberClass() && !java.lang.reflect.Modifier.isStatic(c.getModifiers())) return false;\n  try { c.getDeclaredConstructor(); return true; } catch (NoSuchMethodException e) { return false; }\n}","tryCatchPattern":null,"preventionTips":["Declare Structure subclasses static or top-level with a public no-arg constructor","Never throw from Structure field initializers/constructors","Exclude Structure classes from ProGuard/R8 obfuscation","Smoke-test native structure returns in unit tests"],"tags":["jni","structure","reflection","instantiation"],"backgroundTag":"invalid-constructor-argument","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"}