{"record":{"id":"3e0fc6cad4a7e2e2","repo":"java-native-access/jna","slug":"error-looking-up-function-functionname-cause","errorCode":null,"errorMessage":"Error looking up function '<functionName>': <cause>","messagePattern":"Error looking up function '<functionName>': <cause>","errorType":"exception","errorClass":"UnsatisfiedLinkError","httpStatus":null,"severity":"error","filePath":"src/com/sun/jna/Function.java","lineNumber":253,"sourceCode":"     * @param  encoding\n     *                 Encoding for conversion between Java and native strings.\n     * @throws UnsatisfiedLinkError if the given function name is\n     * not found within the library.\n     */\n    Function(NativeLibrary library, String functionName, int callFlags, String encoding) {\n        checkCallingConvention(callFlags & MASK_CC);\n        if (functionName == null) {\n            throw new NullPointerException(\"Function name must not be null\");\n        }\n        this.library = library;\n        this.functionName = functionName;\n        this.callFlags = callFlags;\n        this.options = library.getOptions();\n        this.encoding = encoding != null ? encoding : Native.getDefaultStringEncoding();\n        try {\n            this.peer = library.getSymbolAddress(functionName);\n        } catch(UnsatisfiedLinkError e) {\n            throw new UnsatisfiedLinkError(\"Error looking up function '\"\n                                           + functionName + \"': \"\n                                           + e.getMessage());\n        }\n    }\n\n    /**\n     * Create a new <code>Function</code> that is linked with a native\n     * function that follows the given calling convention.\n     *\n     * <p>The allocated instance represents a pointer to the given\n     * function address, called with the given calling\n     * convention.\n     *\n     * @param  functionAddress\n     *                 Address of the native function\n     * @param  callFlags\n     *                 Function <a href=\"#callflags\">call flags</a>\n     * @param  encoding","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Function.java#L235-L271","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the function name with nm -D lib.so / dumpbin /exports and fix the Java interface method name","Ensure the correct version/architecture of the native library is being loaded (check java.library.path and loaded library file)","Add the function's defining library to the dependency set (the symbol may live in a different shared object)","Wrap the Native.load call in try/catch for UnsatisfiedLinkError and fail fast with a clear message"],"exampleFix":"// before\nMyLib lib = Native.load(\"mylib\", MyLib.class);\nlib.someFuntion(x); // typo\n// after\nMyLib lib = Native.load(\"mylib\", MyLib.class);\nlib.someFunction(x); // matches exported symbol","handlingStrategy":"try-catch","validationCode":"// resolve and check the symbol before use\ntry {\n    Pointer p = NativeLibrary.getInstance(\"mylib\").getSymbolAddress(\"someFunction\");\n} catch (UnsatisfiedLinkError e) {\n    throw new IllegalStateException(\"Symbol someFunction missing from mylib\", e);\n}","typeGuard":"boolean hasSymbol(NativeLibrary lib, String name) {\n    try { lib.getSymbolAddress(name); return true; }\n    catch (UnsatisfiedLinkError e) { return false; }\n}","tryCatchPattern":"try {\n    MyLib lib = Native.load(\"mylib\", MyLib.class);\n    lib.someFunction(arg);\n} catch (UnsatisfiedLinkError e) {\n    // log e.getMessage() which names the function and cause; degrade or fail fast\n}","preventionTips":["Cross-check every interface method name against nm/dumpbin exports of the actual shipped native library","Add a startup smoke test that resolves all bound symbols once at boot","Pin the native library version your bindings were generated from"],"tags":["jna","native","symbol-lookup","unsatisfied-link"],"backgroundTag":"resource-not-found","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"}