elastic/elasticsearch · error · IllegalStateException

missing implementation for

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.

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 provider jars list
• AssignProcessToJobObject
• automatic module without a manifest name is not supported…
• could not add [ ] to tar file [ ]
• Could not close systemd socket

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

Appendix: 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)