java-native-access/jna · error · UnsatisfiedLinkError

Error looking up function '<functionName>': <cause>

Error message

Error looking up function '<functionName>': <cause>

What it means

JNA wraps the native symbol lookup failure in a new UnsatisfiedLinkError when constructing a Function from a library. The original error's message is preserved as the cause text, indicating that dlsym/GetProcAddress could not resolve '<functionName>' in the loaded native library. This means the library loaded but the named function does not exist or is not exported.

Source

Thrown at src/com/sun/jna/Function.java:253

     * @param  encoding
     *                 Encoding for conversion between Java and native strings.
     * @throws UnsatisfiedLinkError if the given function name is
     * not found within the library.
     */
    Function(NativeLibrary library, String functionName, int callFlags, String encoding) {
        checkCallingConvention(callFlags & MASK_CC);
        if (functionName == null) {
            throw new NullPointerException("Function name must not be null");
        }
        this.library = library;
        this.functionName = functionName;
        this.callFlags = callFlags;
        this.options = library.getOptions();
        this.encoding = encoding != null ? encoding : Native.getDefaultStringEncoding();
        try {
            this.peer = library.getSymbolAddress(functionName);
        } catch(UnsatisfiedLinkError e) {
            throw new UnsatisfiedLinkError("Error looking up function '"
                                           + functionName + "': "
                                           + e.getMessage());
        }
    }

    /**
     * Create a new <code>Function</code> that is linked with a native
     * function that follows the given calling convention.
     *
     * <p>The allocated instance represents a pointer to the given
     * function address, called with the given calling
     * convention.
     *
     * @param  functionAddress
     *                 Address of the native function
     * @param  callFlags
     *                 Function <a href="#callflags">call flags</a>
     * @param  encoding

View on GitHub (pinned to d036ad9781)

Solutions

1. Verify the function name with nm -D lib.so / dumpbin /exports and fix the Java interface method name
2. Ensure the correct version/architecture of the native library is being loaded (check java.library.path and loaded library file)
3. Add the function's defining library to the dependency set (the symbol may live in a different shared object)
4. Wrap the Native.load call in try/catch for UnsatisfiedLinkError and fail fast with a clear message

Example fix

// before
MyLib lib = Native.load("mylib", MyLib.class);
lib.someFuntion(x); // typo
// after
MyLib lib = Native.load("mylib", MyLib.class);
lib.someFunction(x); // matches exported symbol

// resolve and check the symbol before use
try {
    Pointer p = NativeLibrary.getInstance("mylib").getSymbolAddress("someFunction");
} catch (UnsatisfiedLinkError e) {
    throw new IllegalStateException("Symbol someFunction missing from mylib", e);
}

boolean hasSymbol(NativeLibrary lib, String name) {
    try { lib.getSymbolAddress(name); return true; }
    catch (UnsatisfiedLinkError e) { return false; }
}

try {
    MyLib lib = Native.load("mylib", MyLib.class);
    lib.someFunction(arg);
} catch (UnsatisfiedLinkError e) {
    // log e.getMessage() which names the function and cause; degrade or fail fast
}

When it happens

Trigger: Calling Native.load(...).<method> or new Function(library, name, ...) where the native library exports no symbol matching the function name; misspelled function name; name only available via a macro/inline; wrong library version.

Common situations: Binding against a different installed version of the native library that lacks the symbol; forgetting that C preprocessor macros never create symbols; 32/64-bit or stripped library variants; calling a Windows-only function on Linux.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Win32Exception(rc)
• Win32Exception(Kernel32.INSTANCE.GetLastError())
• Function address may not be null
• No method method.getName() with signature sig in cls
• Error looking up 'symbolName': e.getMessage()

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