java-native-access/jna · error

JNA: failed to create structure

Error message

JNA: failed to create structure

What it means

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.

Solutions

1. Ensure the Structure subclass is a static (or top-level) class with a public no-argument constructor.
2. Check stderr/heap dump for the original JNI exception (NoSuchMethodException/InvocationTargetException) raised before this message.
3. Keep-keep rules: exclude JNA Structure classes from ProGuard/R8 shrinking.
4. Verify the field/return type declared in the mapping actually matches the Structure class being constructed.

Example fix

// before
class Outer { class Point extends Structure { ... } } // inner class, no no-arg ctor
// after
class Outer { public static class Point extends Structure { public Point() {} ... } }

// Before passing a Structure subclass to a mapping, verify construction:
try {
  Class<?> c = structClass;
  if (c.isMemberClass() && !java.lang.reflect.Modifier.isStatic(c.getModifiers()))
      throw new IllegalArgumentException("Structure must be static/top-level");
  c.getDeclaredConstructor().setAccessible(true);
} catch (NoSuchMethodException e) { /* fix class: add public no-arg ctor */ }

static boolean isInstantiableStructure(Class<?> c) {
  if (!Structure.class.isAssignableFrom(c)) return false;
  if (c.isMemberClass() && !java.lang.reflect.Modifier.isStatic(c.getModifiers())) return false;
  try { c.getDeclaredConstructor(); return true; } catch (NoSuchMethodException e) { return false; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Can't instantiate " + type
• Can't create an instance of
• Can't determine size of nested structure
• Exception reading field '" + f.getName() + "' in " +…
• Exception thrown while instantiating an instance of " + type

AI-assisted analysis of java-native-access/jna@d036ad9781 (2026-09-12). Data as JSON: /api/errors/f3aebabe735c80c3. Report an issue: GitHub.

Appendix: source

Thrown at native/dispatch.c:974

}

jobject
newJavaPointer(JNIEnv *env, void *p)
{
    jobject obj = NULL;
    if (p != NULL) {
      obj = (*env)->NewObject(env, classPointer, MID_Pointer_init, A2L(p));
    }
    return obj;
}

jobject
newJavaStructure(JNIEnv *env, void *data, jclass type)
{
  if (data != NULL) {
    volatile jobject obj = (*env)->CallStaticObjectMethod(env, classStructure, MID_Structure_newInstance, type, A2L(data));
    if (obj == NULL) {
      fprintf(stderr, "JNA: failed to create structure\n");
    }
    return obj;
  }
  return NULL;
}

jobject
newJavaCallback(JNIEnv* env, void* fptr, jclass type)
{
  if (fptr != NULL) {
    jobject ptr = newJavaPointer(env, fptr);
    return (*env)->CallStaticObjectMethod(env, classCallbackReference,
                                          MID_CallbackReference_getCallback,
                                          type, ptr, JNI_TRUE);
  }
  return NULL;
}

View on GitHub (pinned to d036ad9781)