java-native-access/jna · error

JNA: Unhandled result conversion: %d

Error message

JNA: Unhandled result conversion: %d

What it means

In invoke_callback, JNA converts the native callback return value to a Java type based on a conversion flag (cb->rflag). If the flag is not one of the recognized CVT_* values, JNA prints this diagnostic to stderr and leaves the raw pointer in resp, meaning the Java callback will receive an incorrectly converted (or raw) return value. It indicates an internal inconsistency between the Java-side callback setup and the native conversion table.

Source

Thrown at native/callback.c:531

      break;
    case CVT_WSTRING: 
      *(void **)resp = getNativeString(env, *(void **)resp, JNI_TRUE);
      break;
    case CVT_STRUCTURE:
      writeStructure(env, *(void **)resp);
      *(void **)resp = getStructureAddress(env, *(void **)resp);
      break;
    case CVT_STRUCTURE_BYVAL:
      writeStructure(env, *(void **)resp);
      memcpy(oldresp, getStructureAddress(env, *(void **)resp), cb->cif.rtype->size);
      break;
    case CVT_CALLBACK: 
      *(void **)resp = getCallbackAddress(env, *(void **)resp);
      break;
    case CVT_DEFAULT:
      break;
    default:
      fprintf(stderr, "JNA: Unhandled result conversion: %d\n", cb->rflag);
      break;
    }
    if (cb->conversion_flags) {
      for (i=0;i < cif->nargs;i++) {
        if (cb->conversion_flags[i] == CVT_STRUCTURE) {
          writeStructure(env, *(void **)cbargs[i]);
        }
      }
    }
  }
  else {
    jobject result;
    jobjectArray params =
      (*env)->NewObjectArray(env, cif->nargs, classObject, NULL);
    unsigned int i;

    for (i=0;i < cif->nargs;i++) {
      jobject arg = new_object(env, cb->arg_jtypes[i], cbargs[i], JNI_FALSE, cb->encoding);

View on GitHub (pinned to d036ad9781)

Solutions

1. Update JNA to the latest version so the jar and native library match.
2. Change the callback's Java return type to a type JNA explicitly supports (void, primitive, Pointer, Structure, String, etc.).
3. Inspect cb->rflag setup in callback.c/Java callback registration to find which type maps to the unknown flag value.
4. File a JNA bug with the printed rflag integer if the type should be supported.

Example fix

// before
public int call() { ... } // exotic native-mapped mapping producing unknown rflag
// after
public NativeLong call() { ... } // or another explicitly supported return type

// Java: before registering, confirm the callback's return type is JNA-supported
Class<?> r = callback.getClass().getMethod("callback").getReturnType();
boolean ok = r == void.class || r.isPrimitive() || Pointer.class.isAssignableFrom(r)
          || Structure.class.isAssignableFrom(r) || String.class == r;

static boolean isSupportedReturnType(Class<?> t) {
  return t == void.class || t.isPrimitive() || Number.class.isAssignableFrom(t)
      || t == Boolean.class || t == Character.class || Pointer.class.isAssignableFrom(t)
      || Structure.class.isAssignableFrom(t) || t == String.class;
}

When it happens

Trigger: A Callback with a native-mapped return type whose resulting conversion flag (rflag) was never assigned a known CVT_* value during callback initialization; effectively any unmapped/unexpected return type reaching dispatch_callback.

Common situations: Custom or exotic return types in native-mapped callbacks, version skew between the JNA jar and its packed native library, or platform-specific return-type mappings not covered by the installed native build.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• JNA: extract_value: %s
• Win32Exception from native GetLastError after FindResource f
• Win32Exception from native GetLastError after LoadResource f
• Win32Exception from native GetLastError when SizeofResource
• LockResource returned null.

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