apache/pulsar · error · MetadataException

METADATA_SERVICE_ERROR

METADATA_SERVICE_ERROR

Error message

MetadataException

What it means

MetadataException with code METADATA_SERVICE_ERROR thrown by AbstractMetadataDriver.initialize when initializing the PulsarLedgerManagerFactory against the metadata store fails with an IOException. It wraps a lower-level metadata-store failure (connection, schema/layout, or legacy ledger-manager version mismatch) encountered while setting up the BookKeeper metadata driver.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/AbstractMetadataDriver.java:69

    protected LayoutManager layoutManager;
    @SuppressWarnings("rawtypes")
    protected AbstractConfiguration conf;
    protected String ledgersRootPath;

    @SuppressWarnings("rawtypes")
    protected void initialize(AbstractConfiguration conf) throws MetadataException {
        this.conf = conf;
        this.ledgersRootPath = resolveLedgersRootPath();
        createMetadataStore();
        this.registrationClient = new PulsarRegistrationClient(store, ledgersRootPath);
        createRegistrationManager();
        this.layoutManager = new PulsarLayoutManager(store, ledgersRootPath);
        this.ledgerManagerFactory = new PulsarLedgerManagerFactory();

        try {
            ledgerManagerFactory.initialize(conf, layoutManager, LegacyHierarchicalLedgerManagerFactory.CUR_VERSION);
        } catch (IOException e) {
            throw new MetadataException(Code.METADATA_SERVICE_ERROR, e);
        }
    }

    public RegistrationManager createRegistrationManager() {
        if (registrationManager == null) {
            registrationManager = new PulsarRegistrationManager(store, ledgersRootPath, conf);
        }
        return registrationManager;
    }

    @SneakyThrows
    @Override
    public void close() {
        if (registrationClient != null) {
            registrationClient.close();
        }

        if (registrationManager != null) {

View on GitHub (pinned to 820761864e)

Solutions

1. Verify the metadata service URL and that the metadata store is reachable from this process
2. Ensure the ledgers root path exists and was properly formatted (run metadata initialization/format step)
3. Inspect the wrapped IOException cause (e.getCause()) for the root metadata-store error and fix accordingly
4. Check the ledger manager layout version matches LegacyHierarchicalLedgerManagerFactory.CUR_VERSION

Example fix

// before
MetadataDriver driver = driverFactory.newDriver(conf); // throws MetadataException(METADATA_SERVICE_ERROR)
// after
try {
    MetadataDriver driver = driverFactory.newDriver(conf);
} catch (MetadataException e) {
    if (e.getCode() == Code.METADATA_SERVICE_ERROR) {
        LOG.error("BookKeeper metadata init failed; check metadata store connectivity", e);
    }
    throw e;
}

// before init: check metadata store reachability
MetadataStore ms = ...; ms.get("/admin")
    .orTimeout(5, TimeUnit.SECONDS)
    .join(); // throws if the store is unreachable

try {
    driver.initialize(conf);
} catch (MetadataException e) {
    if (e.getCode() == Code.METADATA_SERVICE_ERROR) {
        LOG.error("BK metadata init failed: {}", e.getCause());
    }
    throw e;
}

When it happens

Trigger: Calling initialize (during BookKeeper cluster/driver setup) when the metadata store is unreachable, ledgersRootPath is missing/inaccessible, or ledgerManagerFactory.initialize fails for the LegacyHierarchicalLedgerManagerFactory version.

Common situations: Metadata service URL misconfigured (wrong zk/metadata store address); metadata store down during broker startup; ledgers root not formatted/created; incompatible BookKeeper ledger manager version in the layout.

Related errors

• failed to init BookieId list
• failed initialized
• The path ${path} doesn't look like a valid path for a Bookie
• IOException
• IOException

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