{"record":{"id":"68212c0a960d4795","repo":"java-native-access/jna","slug":"object-is-not-a-properly-initialized-library-interface","errorCode":null,"errorMessage":"Object is not a properly initialized Library interface instance","messagePattern":"Object is not a properly initialized Library interface instance","errorType":"exception","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Native.java","lineNumber":2045,"sourceCode":"\n    /**\n     * Get the {@link NativeLibrary} instance that is wrapped by the given\n     * {@link Library} interface instance.\n     *\n     * @param library the {@link Library} interface instance, which was created\n     * by the {@link Native#load Native.load()} method\n     * @return the wrapped {@link NativeLibrary} instance\n     */\n    public static NativeLibrary getNativeLibrary(final Library library) {\n        if(library == null) {\n            throw new IllegalArgumentException(\"null passed to getNativeLibrary\");\n        }\n        if(! Proxy.isProxyClass(library.getClass())) {\n            throw new IllegalArgumentException(\"library object passed to getNativeLibrary in not a proxy\");\n        }\n        final InvocationHandler handler = Proxy.getInvocationHandler(library);\n        if (!(handler instanceof Library.Handler)) {\n            throw new IllegalArgumentException(\"Object is not a properly initialized Library interface instance\");\n        }\n        return ((Library.Handler) handler).getNativeLibrary();\n    }\n\n    /**\n     * Get the {@link NativeLibrary} instance to which the given \"registered\"\n     * class is bound.\n     *\n     * @param cls the \"registered\" class, which was previously registered via\n     * the {@link Native#register register()} method\n     * @return the {@link NativeLibrary} instance to which the \"registered\"\n     * class is bound\n     */\n    public static NativeLibrary getNativeLibrary(final Class<?> cls) {\n        if(cls == null) {\n            throw new IllegalArgumentException(\"null passed to getNativeLibrary\");\n        }\n        final Class<?> mappedClass = findDirectMappedClass(cls);","sourceCodeStart":2027,"sourceCodeEnd":2063,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Native.java#L2027-L2063","documentation":"The Library object is a dynamic proxy but its InvocationHandler is not Library.Handler, meaning it was not produced by JNA's load machinery. JNA throws this IllegalArgumentException because it cannot recover a NativeLibrary from an unrecognized handler.","triggerScenarios":"Passing a JDK Proxy.newProxyInstance-created proxy implementing a Library interface, or a proxy created by an older/incompatible JNA version whose Handler class differs.","commonSituations":"Mixing two JNA versions on the classpath so the proxy was made by a different ClassLoader's Handler class; custom proxies built for logging around library calls.","solutions":["Create the proxy via Native.load() instead of Proxy.newProxyInstance.","Deduplicate JNA jars on the classpath so only one version loads the library.","Obtain the NativeLibrary at load time (NativeLibrary.getInstance) rather than unwrapping a foreign proxy."],"exampleFix":"// before\nMyLib p = (MyLib) Proxy.newProxyInstance(...); // foreign handler\nNativeLibrary nl = Native.getNativeLibrary(p);\n// after\nMyLib p = Native.load(\"mylib\", MyLib.class);\nNativeLibrary nl = Native.getNativeLibrary(p);","handlingStrategy":"type-guard","validationCode":"InvocationHandler h = lib != null && Proxy.isProxyClass(lib.getClass())\n    ? Proxy.getInvocationHandler(lib) : null;\nif (!(h instanceof Library.Handler)) {\n    throw new IllegalStateException(\"Proxy was not created by JNA Native.load()\");\n}","typeGuard":"boolean isProperlyInitializedLibrary(Library lib) {\n    return lib != null && Proxy.isProxyClass(lib.getClass())\n        && Proxy.getInvocationHandler(lib) instanceof Library.Handler;\n}","tryCatchPattern":"try {\n    NativeLibrary nl = Native.getNativeLibrary(lib);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"not a properly initialized Library\")) {\n        throw new IllegalStateException(\"Foreign proxy; reload via Native.load()\", e);\n    }\n    throw e;\n}","preventionTips":["Ensure only one JNA version is on the classpath (mvn dependency:tree).","Never build Library proxies manually with Proxy.newProxyInstance.","Re-create the proxy with Native.load() after any classloader change."],"tags":["jna","proxy","invocation-handler","initialization"],"backgroundTag":"invalid-argument-value","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"}