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

Object is not a properly initialized Library interface insta

Error message

Object is not a properly initialized Library interface instance

What it means

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.

Source

Thrown at src/com/sun/jna/Native.java:2045

    /**
     * Get the {@link NativeLibrary} instance that is wrapped by the given
     * {@link Library} interface instance.
     *
     * @param library the {@link Library} interface instance, which was created
     * by the {@link Native#load Native.load()} method
     * @return the wrapped {@link NativeLibrary} instance
     */
    public static NativeLibrary getNativeLibrary(final Library library) {
        if(library == null) {
            throw new IllegalArgumentException("null passed to getNativeLibrary");
        }
        if(! Proxy.isProxyClass(library.getClass())) {
            throw new IllegalArgumentException("library object passed to getNativeLibrary in not a proxy");
        }
        final InvocationHandler handler = Proxy.getInvocationHandler(library);
        if (!(handler instanceof Library.Handler)) {
            throw new IllegalArgumentException("Object is not a properly initialized Library interface instance");
        }
        return ((Library.Handler) handler).getNativeLibrary();
    }

    /**
     * Get the {@link NativeLibrary} instance to which the given "registered"
     * class is bound.
     *
     * @param cls the "registered" class, which was previously registered via
     * the {@link Native#register register()} method
     * @return the {@link NativeLibrary} instance to which the "registered"
     * class is bound
     */
    public static NativeLibrary getNativeLibrary(final Class<?> cls) {
        if(cls == null) {
            throw new IllegalArgumentException("null passed to getNativeLibrary");
        }
        final Class<?> mappedClass = findDirectMappedClass(cls);

View on GitHub (pinned to d036ad9781)

Solutions

1. Create the proxy via Native.load() instead of Proxy.newProxyInstance.
2. Deduplicate JNA jars on the classpath so only one version loads the library.
3. Obtain the NativeLibrary at load time (NativeLibrary.getInstance) rather than unwrapping a foreign proxy.

Example fix

// before
MyLib p = (MyLib) Proxy.newProxyInstance(...); // foreign handler
NativeLibrary nl = Native.getNativeLibrary(p);
// after
MyLib p = Native.load("mylib", MyLib.class);
NativeLibrary nl = Native.getNativeLibrary(p);

InvocationHandler h = lib != null && Proxy.isProxyClass(lib.getClass())
    ? Proxy.getInvocationHandler(lib) : null;
if (!(h instanceof Library.Handler)) {
    throw new IllegalStateException("Proxy was not created by JNA Native.load()");
}

boolean isProperlyInitializedLibrary(Library lib) {
    return lib != null && Proxy.isProxyClass(lib.getClass())
        && Proxy.getInvocationHandler(lib) instanceof Library.Handler;
}

try {
    NativeLibrary nl = Native.getNativeLibrary(lib);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("not a properly initialized Library")) {
        throw new IllegalStateException("Foreign proxy; reload via Native.load()", e);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unrecognized proxy handler: ih
• Failed to create WbemLocator object.
• library object passed to getNativeLibrary in not a proxy
• Array fields must be initialized
• Native library not initialized

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