java-native-access/jna · error · IllegalArgumentException

<libname> does not implement an interface: <interfaceClassNa

Error message

<libname> does not implement an interface: <interfaceClassName>

What it means

Library.Handler's constructor throws this IllegalArgumentException when the class supplied to Native.load is not a Java interface. JNA library mappings must be interfaces whose methods are mapped to native functions; a concrete class cannot be proxied this way.

Source

Thrown at src/com/sun/jna/Library.java:183

                this.parameterTypes = parameterTypes;
                this.methodHandle = null;
            }
        }

        private final NativeLibrary nativeLibrary;
        private final Class<?> interfaceClass;
        // Library invocation options
        private final Map<String, Object> options;
        private final InvocationMapper invocationMapper;
        private final Map<Method, FunctionInfo> functions = new WeakHashMap<>();
        public Handler(String libname, Class<?> interfaceClass, Map<String, ?> options) {

            if (libname != null && "".equals(libname.trim())) {
                throw new IllegalArgumentException("Invalid library name \"" + libname + "\"");
            }

            if (!interfaceClass.isInterface()) {
                throw new IllegalArgumentException(libname + " does not implement an interface: " + interfaceClass.getName());
            }

            this.interfaceClass = interfaceClass;
            this.options = new HashMap<>(options);
            int callingConvention = AltCallingConvention.class.isAssignableFrom(interfaceClass)
                                  ? Function.ALT_CONVENTION
                                  : Function.C_CONVENTION;
            if (this.options.get(OPTION_CALLING_CONVENTION) == null) {
                this.options.put(OPTION_CALLING_CONVENTION, Integer.valueOf(callingConvention));
            }
            if (this.options.get(OPTION_CLASSLOADER) == null) {
                this.options.put(OPTION_CLASSLOADER, interfaceClass.getClassLoader());
            }
            this.nativeLibrary = NativeLibrary.getInstance(libname, this.options);
            invocationMapper = (InvocationMapper)this.options.get(OPTION_INVOCATION_MAPPER);
        }

        public NativeLibrary getNativeLibrary() {

View on GitHub (pinned to d036ad9781)

Solutions

1. Define/extract a Java interface with the native method signatures and pass it to Native.load.
2. If you have an abstract wrapper class, move the native method declarations to an interface it implements.
3. Verify with clazz.isInterface() before calling Native.load in generic code.

Example fix

// before
MyLib lib = Native.load("mylib", MyLibImpl.class);
// after
public interface MyLib { int fn(int x); }
MyLib lib = Native.load("mylib", MyLib.class);

static void requireInterface(Class<?> c) {
  if (!c.isInterface()) throw new IllegalArgumentException(c.getName() + " must be an interface for Native.load");
}

static <T> T loadIfInterface(String lib, Class<T> iface) {
  if (!iface.isInterface()) throw new IllegalArgumentException("Pass an interface, got class " + iface.getName());
  return Native.load(lib, iface);
}

try {
  MyLib lib = Native.load("mylib", MyLib.class);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("does not implement an interface")) {
    throw new IllegalStateException("Extract a mapping interface from " + e.getMessage(), e);
  }
  throw e;
}

When it happens

Trigger: Native.load("mylib", SomeClass.class) where SomeClass is a class, abstract class, or annotation type rather than an interface.

Common situations: Refactoring that turned the mapping interface into a class; passing an implementation class instead of its interface; copy-pasting the wrong Class literal into Native.load.

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

• Invalid library name "<libname>"
• Failed to load library 'libraryName'
• Callback type must be an interface
• <type> is not derived from com.sun.jna.Callback
• There is an incompatible JNA native library installed on thi

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