What causes "Class cls.getName() is not currently registered" in java-native-access/jna?

Call Native.register(cls, nativeLibrary) before querying getNativeLibrary.

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

Class cls.getName() is not currently registered

Error message

Class cls.getName() is not currently registered

What it means

This IllegalArgumentException means the class (or its direct-mapped equivalent) has no entry in JNA's registeredLibraries map — Native.register() was never called for it, or registration happened in a different classloader/session. The registry is keyed by the class findDirectMappedClass(cls) returns, so a mismatch there also lands here.

Source

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

    /**
     * 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);
        synchronized(registeredClasses) {
            final NativeLibrary nativeLibrary = registeredLibraries.get(mappedClass);
            if (nativeLibrary == null) {
                throw new IllegalArgumentException("Class " + cls.getName() + " is not currently registered");
            } else {
                return nativeLibrary;
            }
        }
    }

    /* Take note of options used for a given library mapping, to facilitate
     * looking them up later.
     */
    private static Map<String, Object> cacheOptions(Class<?> cls, Map<String, ?> options, Object proxy) {
        Map<String, Object> libOptions = new HashMap<>(options);
        libOptions.put(_OPTION_ENCLOSING_LIBRARY, cls);
        typeOptions.put(cls, libOptions);
        if (proxy != null) {
            libraries.put(cls, new WeakReference<>(proxy));
        }

        // If it's a direct mapping, AND implements a Library interface,

View on GitHub (pinned to d036ad9781)

Solutions

Call Native.register(cls, nativeLibrary) before querying getNativeLibrary.
Use the same ClassLoader for registration and lookup; deduplicate JNA on the classpath.
Verify findDirectMappedClass matches: query with the exact class that was registered.
Check that registration did not throw earlier and fail silently.

Example fix

// before
NativeLibrary nl = Native.getNativeLibrary(MyNative.class); // not yet registered
// after
Native.register(MyNative.class, NativeLibrary.getInstance("mylib"));
NativeLibrary nl = Native.getNativeLibrary(MyNative.class);

Defensive patterns

Strategy: validation

Validate before calling

synchronized (Native.class) {
    if (!isRegistered) {
        Native.register(MyNative.class, NativeLibrary.getInstance("mylib"));
        isRegistered = true;
    }
}
NativeLibrary nl = Native.getNativeLibrary(MyNative.class);

Try / catch

try {
    NativeLibrary nl = Native.getNativeLibrary(MyNative.class);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().endsWith("is not currently registered")) {
        ensureRegistered(); // idempotent register()
        nl = Native.getNativeLibrary(MyNative.class);
    } else {
        throw e;
    }
}

Prevention

Register classes in a static initializer or explicit init() that always runs before use.
In app servers/OSGi, register and look up within the same classloader.
Make registration idempotent and call it lazily on first access.
Log registration success so failures are visible.

When it happens

Trigger: Calling Native.getNativeLibrary(SomeClass.class) before Native.register(SomeClass.class, lib) ran; querying after a failed registration; calling from a different ClassLoader (app servers, plugin systems); passing a class that is a companion of, but not itself, the registered one.

Common situations: Static initialization order bugs; OSGi/webapp reload losing the registration; assuming register() side effects from a different library version.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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