apache/pulsar · error · MetadataStoreException.InvalidImplementationException

Implementation does not comply with org.apache.pulsar.metada

Error message

Implementation does not comply with org.apache.pulsar.metadata.api.extended.MetadataStoreExtended

What it means

MetadataStoreFactoryImpl.createExtended() instantiates a store from a metadata URL and requires the result to implement MetadataStoreExtended (which exposes extended APIs like metadata caches/coordination). If the provider's implementation only implements the basic MetadataStore interface, it throws MetadataStoreException.InvalidImplementationException with this message.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/impl/MetadataStoreFactoryImpl.java:51

import org.apache.pulsar.metadata.api.extended.MetadataStoreExtended;
import org.apache.pulsar.metadata.impl.oxia.OxiaMetadataStoreProvider;

@CustomLog
public class MetadataStoreFactoryImpl {

    public static final String METADATASTORE_PROVIDERS_PROPERTY = "pulsar.metadatastore.providers";

    public static MetadataStore create(String metadataURL, MetadataStoreConfig metadataStoreConfig) throws
            MetadataStoreException {
        return newInstance(metadataURL, metadataStoreConfig, false);
    }

    public static MetadataStoreExtended createExtended(String metadataURL, MetadataStoreConfig metadataStoreConfig)
            throws
            MetadataStoreException {
        MetadataStore store = MetadataStoreFactoryImpl.newInstance(metadataURL, metadataStoreConfig, true);
        if (!(store instanceof MetadataStoreExtended)) {
            throw new MetadataStoreException.InvalidImplementationException(
                    "Implementation does not comply with " + MetadataStoreExtended.class.getName());
        }

        return (MetadataStoreExtended) store;
    }

    private static MetadataStore newInstance(String metadataURL, MetadataStoreConfig metadataStoreConfig,
                                             boolean enableSessionWatcher)
            throws MetadataStoreException {
        MetadataStoreProvider provider = findProvider(metadataURL);
        return provider.create(metadataURL, metadataStoreConfig, enableSessionWatcher);
    }

    @SuppressWarnings("auxiliaryclass")
    static Map<String, MetadataStoreProvider> loadProviders() {
        Map<String, MetadataStoreProvider> providers = new HashMap<>();
        providers.put(MEMORY_SCHEME_IDENTIFIER, new MemoryMetadataStoreProvider());
        providers.put(ROCKSDB_SCHEME_IDENTIFIER, new RocksdbMetadataStoreProvider());

View on GitHub (pinned to 820761864e)

Solutions

1. Use a metadata URL scheme backed by a MetadataStoreExtended implementation (zk:, oxia:, rocksdb:, memory:)
2. Upgrade or fix the custom provider to implement org.apache.pulsar.metadata.api.extended.MetadataStoreExtended
3. If only basic MetadataStore is needed, call MetadataStoreFactory.create() instead of createExtended()

Example fix

// before
MetadataStoreExtended store = MetadataStoreFactoryImpl.createExtended("mem://", cfg); // provider not extended
// after
MetadataStoreExtended store = MetadataStoreFactoryImpl.createExtended("rocksdb:///data/metadata", cfg);

// Java
MetadataStore store = MetadataStoreFactory.create(metadataURL, config);
if (!(store instanceof MetadataStoreExtended)) {
    throw new IllegalArgumentException("Provider for " + metadataURL + " lacks extended API");
}

boolean supportsExtended(String metadataURL, MetadataStoreConfig cfg) throws MetadataStoreException {
    return MetadataStoreFactory.create(metadataURL, cfg) instanceof MetadataStoreExtended;
}

try {
    MetadataStoreExtended s = MetadataStoreFactoryImpl.createExtended(url, cfg);
} catch (MetadataStoreException.InvalidImplementationException e) {
    // switch to a scheme backed by MetadataStoreExtended (zk:, oxia:, rocksdb:, memory:)
}

When it happens

Trigger: Calling MetadataStoreFactoryImpl.createExtended("...", config) with a URL scheme whose provider class implements MetadataStore but not MetadataStoreExtended.

Common situations: Custom or minimal metadata store providers registered via ServiceLoader that never implemented the extended interface; plugging a legacy provider into code that requires extended APIs (e.g., Pulsar broker startup with a custom metadata URL).

Related errors

• Metadata store address argument is required (--metadata-stor
• Failed to validate global cluster configuration
• Concurrent modification
• e
• RestException(e)

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/997303eebced9522. Report an issue: GitHub.