{"record":{"id":"2287741e273d0887","repo":"java-native-access/jna","slug":"libname-does-not-implement-an-interface-interfaceclassname","errorCode":null,"errorMessage":"<libname> does not implement an interface: <interfaceClassName>","messagePattern":"<libname> does not implement an interface: <interfaceClassName>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Library.java","lineNumber":183,"sourceCode":"                this.parameterTypes = parameterTypes;\n                this.methodHandle = null;\n            }\n        }\n\n        private final NativeLibrary nativeLibrary;\n        private final Class<?> interfaceClass;\n        // Library invocation options\n        private final Map<String, Object> options;\n        private final InvocationMapper invocationMapper;\n        private final Map<Method, FunctionInfo> functions = new WeakHashMap<>();\n        public Handler(String libname, Class<?> interfaceClass, Map<String, ?> options) {\n\n            if (libname != null && \"\".equals(libname.trim())) {\n                throw new IllegalArgumentException(\"Invalid library name \\\"\" + libname + \"\\\"\");\n            }\n\n            if (!interfaceClass.isInterface()) {\n                throw new IllegalArgumentException(libname + \" does not implement an interface: \" + interfaceClass.getName());\n            }\n\n            this.interfaceClass = interfaceClass;\n            this.options = new HashMap<>(options);\n            int callingConvention = AltCallingConvention.class.isAssignableFrom(interfaceClass)\n                                  ? Function.ALT_CONVENTION\n                                  : Function.C_CONVENTION;\n            if (this.options.get(OPTION_CALLING_CONVENTION) == null) {\n                this.options.put(OPTION_CALLING_CONVENTION, Integer.valueOf(callingConvention));\n            }\n            if (this.options.get(OPTION_CLASSLOADER) == null) {\n                this.options.put(OPTION_CLASSLOADER, interfaceClass.getClassLoader());\n            }\n            this.nativeLibrary = NativeLibrary.getInstance(libname, this.options);\n            invocationMapper = (InvocationMapper)this.options.get(OPTION_INVOCATION_MAPPER);\n        }\n\n        public NativeLibrary getNativeLibrary() {","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Library.java#L165-L201","documentation":"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.","triggerScenarios":"Native.load(\"mylib\", SomeClass.class) where SomeClass is a class, abstract class, or annotation type rather than an interface.","commonSituations":"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.","solutions":["Define/extract a Java interface with the native method signatures and pass it to Native.load.","If you have an abstract wrapper class, move the native method declarations to an interface it implements.","Verify with clazz.isInterface() before calling Native.load in generic code."],"exampleFix":"// before\nMyLib lib = Native.load(\"mylib\", MyLibImpl.class);\n// after\npublic interface MyLib { int fn(int x); }\nMyLib lib = Native.load(\"mylib\", MyLib.class);","handlingStrategy":"type-guard","validationCode":"static void requireInterface(Class<?> c) {\n  if (!c.isInterface()) throw new IllegalArgumentException(c.getName() + \" must be an interface for Native.load\");\n}","typeGuard":"static <T> T loadIfInterface(String lib, Class<T> iface) {\n  if (!iface.isInterface()) throw new IllegalArgumentException(\"Pass an interface, got class \" + iface.getName());\n  return Native.load(lib, iface);\n}","tryCatchPattern":"try {\n  MyLib lib = Native.load(\"mylib\", MyLib.class);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"does not implement an interface\")) {\n    throw new IllegalStateException(\"Extract a mapping interface from \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Always define native mappings as interfaces.","Keep implementation classes separate from the JNA mapping interface.","Add a startup assert clazz.isInterface() in generic loader helpers.","Never pass annotation types or abstract classes to Native.load."],"tags":["jna","native-library","interface","library-loading"],"backgroundTag":"type-mismatch","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}