elastic/elasticsearch · error · IllegalStateException

{providerName} missing implementation for {libraryClass}

Error message

{providerName} missing implementation for {libraryClass}

What it means

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.

Source

Thrown at libs/native/src/main/java/org/elasticsearch/nativeaccess/lib/NativeLibraryProvider.java:49

    }

    /** Returns a human-understandable name for this provider. */
    public String getName() {
        return name;
    }

    /**
     * Returns an instance of the given library class. Checks the new per-library
     * {@link LibraryProvider} lookup first, then falls back to this provider's map.
     */
    public <T> T getLibrary(Class<T> cls) {
        T result = LibraryProvider.lookupLibrary(cls);
        if (result != null) {
            return result;
        }
        Supplier<?> libraryCtor = libraries.get(cls);
        if (libraryCtor == null) {
            throw new IllegalStateException(getClass().getSimpleName() + " missing implementation for " + cls.getSimpleName());
        }
        Object library = libraryCtor.get();
        assert library != null;
        assert cls.isAssignableFrom(library.getClass());
        return cls.cast(library);
    }

    private static final class Holder {
        private Holder() {}

        static final NativeLibraryProvider INSTANCE = ServiceLoader.load(NativeLibraryProvider.class)
            .findFirst()
            .orElseThrow(() -> new IllegalStateException("No NativeLibraryProvider found"));
    }

    public static NativeLibraryProvider instance() {
        return Holder.INSTANCE;
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. 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).
2. Verify the correct NativeLibraryProvider SPI is on the classpath — check META-INF/services entries and ServiceLoader resolution.
3. 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.
4. Gate OS-specific library lookups behind an OS/platform check so a Windows provider is not asked for a Posix-only library.

Example fix

// before: provider map missing ZstdLibrary
libraries = Map.of(PosixCLibrary.class, PosixCLibrary::instance);

// after: register the implementation
libraries = Map.of(
    PosixCLibrary.class, PosixCLibrary::instance,
    ZstdLibrary.class, ZstdLibrary::instance
);

// Confirm the library class is registered with the active provider before lookup.
Set<Class<?>> registered = provider.registeredLibraryClasses(); // expose for diagnostics
if (!registered.contains(cls) && LibraryProvider.lookupLibrary(cls) == null) {
    throw new IllegalStateException("No implementation for " + cls + " in provider " + provider.getName());
}
return provider.getLibrary(cls);

try {
    return provider.getLibrary(cls);
} catch (IllegalStateException e) {
    throw new IllegalStateException("Native library wiring defect for " + cls + " (provider=" + provider.getName() + ")", e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• missing %s provider jars list
• Unable to locate {} on build classpath.
• Detected class file in distribution ('${file.getName()}')
• failed writing tar file [${tarFile}]
• could not add [${details}] to tar file [${tarFile}]

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/191cba9b50ecf202. Report an issue: GitHub.