{"record":{"id":"80a187558f2b5e0a","repo":"elastic/elasticsearch","slug":"native-function-could-not-be-found","errorCode":null,"errorMessage":"Native function [{}] could not be found","messagePattern":"Native function \\[(.+?)\\] could not be found","errorType":"exception","errorClass":"LinkageError","httpStatus":null,"severity":"critical","filePath":"libs/native/src/main/java/org/elasticsearch/nativeaccess/VecCapsSymbolResolver.java","lineNumber":50,"sourceCode":"     * starting from the supported capability level N, it looks up function_N, function_{N-1}... function.\n     *\n     * @param functionName the base function name, as exported by the native library\n     * @return             a {@link ResolvedSymbol} with the resolved named and address of the native function\n     */\n    @Override\n    public ResolvedSymbol resolve(String functionName, SymbolLookup lookup) {\n        int capability = VecCaps.caps();\n        for (int caps = capability; caps > 0; --caps) {\n            var suffix = caps > 1 ? \"_\" + caps : \"\";\n            var fullFunctionName = functionName + suffix;\n            logger.trace(\"Lookup for {}\", fullFunctionName);\n            var function = lookup.find(functionName + suffix).orElse(null);\n            if (function != null) {\n                logger.debug(\"Binding {}\", fullFunctionName);\n                return new ResolvedSymbol(fullFunctionName, function);\n            }\n        }\n        throw new LinkageError(\"Native function [\" + functionName + \"] could not be found\");\n    }\n}\n","sourceCodeStart":32,"sourceCodeEnd":53,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/native/src/main/java/org/elasticsearch/nativeaccess/VecCapsSymbolResolver.java#L32-L53","documentation":"Thrown as a LinkageError by VecCapsSymbolResolver.resolve() when no capability-level variant (base name, _2, _3, ...) of a requested vector SIMD function is found in the loaded native library via SymbolLookup. This is a fatal startup error: the Java foreign-linker downcall cannot be bound to any native symbol, meaning the simdvec shared library is missing, corrupted, or built without the required kernel.","triggerScenarios":"Occurs during NativeAccessService/SimdVecLibrary initialization when the Panama FFI binder tries to resolve any @Function-annotated method. The resolver iterates from VecCaps.caps() down to 1, appending _N suffixes, and throws LinkageError if none match an exported symbol.","commonSituations":"Custom distribution build that omits or fails to compile the native simdvec library. Architecture mismatch (library compiled for AVX-512 but running on AVX2-only CPU, or vice versa). Library version skew between Java bindings and native code. Container image stripping the .so/.dylib/.dll. Corrupted library file.","solutions":["Ensure the native simdvec library is packaged and on the library path. Check with 'ldd' / 'otool -L' / 'dumpbin'.","Rebuild the native library from the libs/native source for the target platform and architecture.","Inspect exported symbols: 'nm -D libsimdvec.so | grep vec_' to confirm the kernel names exist.","Verify VecCaps.caps() returns a valid capability level for the CPU (check CPUID/flags).","If running a custom distribution, confirm the build system includes the native compilation step."],"exampleFix":"// No code fix; this is a deployment/build issue.\n// Verify the library is loadable:\n//   java -XshowSettings:properties -version  # check java.library.path\n//   nm -D $ES_HOME/lib/libsimdvec.so | grep vec_doti7u\n// Rebuild if symbols are missing:\n//   ./gradlew :libs:native:build","handlingStrategy":"try-catch","validationCode":"// Before relying on native vector kernels, verify the library loads:\ntry {\n    System.loadLibrary(\"simdvec\");\n} catch (UnsatisfiedLinkError e) {\n    logger.error(\"Native simdvec library not found; vector search will use fallback\", e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    simdVecLibrary = nativeAccess.getSimdVecLibrary();\n} catch (LinkageError e) {\n    logger.error(\"Failed to bind native vector kernels; falling back to Java implementation\", e);\n    simdVecLibrary = null; // use pure-Java fallback\n}","preventionTips":["Verify native library presence in CI before running integration tests.","Include native library checksums in distribution validation.","Log VecCaps.caps() at startup to detect CPU capability mismatches early.","Provide a pure-Java fallback path for environments without the native library."],"tags":["native","ffi","symbol-resolution","startup","linkage-error","panama"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}