java-native-access/jna · error · java.lang.IllegalArgumentException

Type must derive from NativeMapped.class

Error message

Type must derive from NativeMapped.class

What it means

NativeMappedConverter's constructor throws IllegalArgumentException when the given class does not implement com.sun.jna.NativeMapped. The converter only knows how to map types that provide custom toNative/fromNative conversions via that interface.

Solutions

1. Make the class implement com.sun.jna.NativeMapped (toNative, fromNative, nativeType methods)
2. Check that the type passed to the mapper/converter is the intended NativeMapped subclass
3. Remove the erroneous type from the type mapper registration

Example fix

// before
class MyType { } // not NativeMapped
new NativeMappedConverter(MyType.class);
// after
class MyType implements NativeMapped {
    public Object toNative() { return ...; }
    public Object fromNative(Object nativeValue, FromNativeContext context) { return ...; }
    public Class<?> nativeType() { return ...; }
}

if (!NativeMapped.class.isAssignableFrom(type)) {
    throw new IllegalArgumentException(type + " must implement NativeMapped");
}

static boolean isNativeMapped(Class<?> c) {
    return NativeMapped.class.isAssignableFrom(c);
}

When it happens

Trigger: Registering or instantiating a type mapping (Native.setTypeMapper, TypeMapper, Structure field mapping) with a class that is not a NativeMapped implementation.

Common situations: Passing the wrong class to a custom TypeMapper; typos in generic types; refactoring removed the implements NativeMapped clause while the mapper still references the type.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Bad volume GUID path format:
• Byte boundary must be positive
• Callback argument <nativeParamTypes[i]> requires custom…
• Invalid Structure field in " + getClass() + ", field name…
• JNA: extract_value

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

Appendix: source

Thrown at src/com/sun/jna/NativeMappedConverter.java:54

    private final Class<?> type;
    private final Class<?> nativeType;
    private final NativeMapped instance;

    public static NativeMappedConverter getInstance(Class<?> cls) {
        synchronized(converters) {
            Reference<NativeMappedConverter> r = converters.get(cls);
            NativeMappedConverter nmc = r != null ? r.get() : null;
            if (nmc == null) {
                nmc = new NativeMappedConverter(cls);
                converters.put(cls, new SoftReference<>(nmc));
            }
            return nmc;
        }
    }

    public NativeMappedConverter(Class<?> type) {
        if (!NativeMapped.class.isAssignableFrom(type))
            throw new IllegalArgumentException("Type must derive from " + NativeMapped.class);
        this.type = type;
        this.instance = defaultValue();
        this.nativeType = instance.nativeType();
    }

    public NativeMapped defaultValue() {
        if (type.isEnum()) {
            return (NativeMapped) type.getEnumConstants()[0];
        }

        return (NativeMapped) Klass.newInstance(type);
    }

    @Override
    public Object fromNative(Object nativeValue, FromNativeContext context) {
        return instance.fromNative(nativeValue, context);
    }

View on GitHub (pinned to d036ad9781)