{"record":{"id":"191cba9b50ecf202","repo":"elastic/elasticsearch","slug":"providername-missing-implementation-for-library","errorCode":null,"errorMessage":"{providerName} missing implementation for {libraryClass}","messagePattern":"(.+?) missing implementation for (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"libs/native/src/main/java/org/elasticsearch/nativeaccess/lib/NativeLibraryProvider.java","lineNumber":49,"sourceCode":"    }\n\n    /** Returns a human-understandable name for this provider. */\n    public String getName() {\n        return name;\n    }\n\n    /**\n     * Returns an instance of the given library class. Checks the new per-library\n     * {@link LibraryProvider} lookup first, then falls back to this provider's map.\n     */\n    public <T> T getLibrary(Class<T> cls) {\n        T result = LibraryProvider.lookupLibrary(cls);\n        if (result != null) {\n            return result;\n        }\n        Supplier<?> libraryCtor = libraries.get(cls);\n        if (libraryCtor == null) {\n            throw new IllegalStateException(getClass().getSimpleName() + \" missing implementation for \" + cls.getSimpleName());\n        }\n        Object library = libraryCtor.get();\n        assert library != null;\n        assert cls.isAssignableFrom(library.getClass());\n        return cls.cast(library);\n    }\n\n    private static final class Holder {\n        private Holder() {}\n\n        static final NativeLibraryProvider INSTANCE = ServiceLoader.load(NativeLibraryProvider.class)\n            .findFirst()\n            .orElseThrow(() -> new IllegalStateException(\"No NativeLibraryProvider found\"));\n    }\n\n    public static NativeLibraryProvider instance() {\n        return Holder.INSTANCE;\n    }","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/libs/native/src/main/java/org/elasticsearch/nativeaccess/lib/NativeLibraryProvider.java#L31-L67","documentation":"Thrown by NativeLibraryProvider.getLibrary(Class) when neither the new per-library LibraryProvider.lookupLibrary(cls) nor this provider's libraries map contains a Supplier for the requested library interface. It is an IllegalStateException signaling a wiring/packaging defect: the SPI provider in use does not ship an implementation for that library class.","triggerScenarios":"Calling getLibrary(SomeLibrary.class) where SomeLibrary was not registered in the provider's map (constructed in the provider subclass) and has not been migrated to the @LibrarySpecification/LookupLibrary system; the wrong NativeLibraryProvider SPI implementation is loaded (e.g. a stub/no-op provider selected by ServiceLoader); a library interface was renamed/moved and the registration was not updated.","commonSituations":"A custom distribution or test fixture that uses a minimal NativeLibraryProvider not registering ZstdLibrary/PosixCLibrary; classpath shading/relocation breaking the ServiceLoader provider match; running on a platform (e.g. Windows) whose provider implementation legitimately omits a Posix-only library but the caller did not gate on OS.","solutions":["Confirm the requested library class is registered in the active provider subclass's constructor map (grep for libraries.put / Map.of in the provider implementations).","Verify the correct NativeLibraryProvider SPI is on the classpath — check META-INF/services entries and ServiceLoader resolution.","If migrating a library to the new system, ensure @LibrarySpecification and the corresponding LibraryProvider.lookupLibrary registration are present before removing it from the legacy map.","Gate OS-specific library lookups behind an OS/platform check so a Windows provider is not asked for a Posix-only library."],"exampleFix":"// before: provider map missing ZstdLibrary\nlibraries = Map.of(PosixCLibrary.class, PosixCLibrary::instance);\n\n// after: register the implementation\nlibraries = Map.of(\n    PosixCLibrary.class, PosixCLibrary::instance,\n    ZstdLibrary.class, ZstdLibrary::instance\n);","handlingStrategy":"validation","validationCode":"// Confirm the library class is registered with the active provider before lookup.\nSet<Class<?>> registered = provider.registeredLibraryClasses(); // expose for diagnostics\nif (!registered.contains(cls) && LibraryProvider.lookupLibrary(cls) == null) {\n    throw new IllegalStateException(\"No implementation for \" + cls + \" in provider \" + provider.getName());\n}\nreturn provider.getLibrary(cls);","typeGuard":null,"tryCatchPattern":"try {\n    return provider.getLibrary(cls);\n} catch (IllegalStateException e) {\n    throw new IllegalStateException(\"Native library wiring defect for \" + cls + \" (provider=\" + provider.getName() + \")\", e);\n}","preventionTips":["Register every library interface the provider must serve in its constructor map.","Verify META-INF/services so the intended NativeLibraryProvider SPI is loaded.","Gate OS-specific library lookups behind an OS/platform check."],"tags":["native","spi","wiring","packaging"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}