{"record":{"id":"246e3a99e9103c44","repo":"apache/pulsar","slug":"metadata-service-error","errorCode":"METADATA_SERVICE_ERROR","errorMessage":"MetadataException","messagePattern":"MetadataException","errorType":"error_code","errorClass":"MetadataException","httpStatus":null,"severity":"error","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/AbstractMetadataDriver.java","lineNumber":69,"sourceCode":"    protected LayoutManager layoutManager;\n    @SuppressWarnings(\"rawtypes\")\n    protected AbstractConfiguration conf;\n    protected String ledgersRootPath;\n\n    @SuppressWarnings(\"rawtypes\")\n    protected void initialize(AbstractConfiguration conf) throws MetadataException {\n        this.conf = conf;\n        this.ledgersRootPath = resolveLedgersRootPath();\n        createMetadataStore();\n        this.registrationClient = new PulsarRegistrationClient(store, ledgersRootPath);\n        createRegistrationManager();\n        this.layoutManager = new PulsarLayoutManager(store, ledgersRootPath);\n        this.ledgerManagerFactory = new PulsarLedgerManagerFactory();\n\n        try {\n            ledgerManagerFactory.initialize(conf, layoutManager, LegacyHierarchicalLedgerManagerFactory.CUR_VERSION);\n        } catch (IOException e) {\n            throw new MetadataException(Code.METADATA_SERVICE_ERROR, e);\n        }\n    }\n\n    public RegistrationManager createRegistrationManager() {\n        if (registrationManager == null) {\n            registrationManager = new PulsarRegistrationManager(store, ledgersRootPath, conf);\n        }\n        return registrationManager;\n    }\n\n    @SneakyThrows\n    @Override\n    public void close() {\n        if (registrationClient != null) {\n            registrationClient.close();\n        }\n\n        if (registrationManager != null) {","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/AbstractMetadataDriver.java#L51-L87","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the metadata service URL and that the metadata store is reachable from this process","Ensure the ledgers root path exists and was properly formatted (run metadata initialization/format step)","Inspect the wrapped IOException cause (e.getCause()) for the root metadata-store error and fix accordingly","Check the ledger manager layout version matches LegacyHierarchicalLedgerManagerFactory.CUR_VERSION"],"exampleFix":"// before\nMetadataDriver driver = driverFactory.newDriver(conf); // throws MetadataException(METADATA_SERVICE_ERROR)\n// after\ntry {\n    MetadataDriver driver = driverFactory.newDriver(conf);\n} catch (MetadataException e) {\n    if (e.getCode() == Code.METADATA_SERVICE_ERROR) {\n        LOG.error(\"BookKeeper metadata init failed; check metadata store connectivity\", e);\n    }\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"// before init: check metadata store reachability\nMetadataStore ms = ...; ms.get(\"/admin\")\n    .orTimeout(5, TimeUnit.SECONDS)\n    .join(); // throws if the store is unreachable","typeGuard":null,"tryCatchPattern":"try {\n    driver.initialize(conf);\n} catch (MetadataException e) {\n    if (e.getCode() == Code.METADATA_SERVICE_ERROR) {\n        LOG.error(\"BK metadata init failed: {}\", e.getCause());\n    }\n    throw e;\n}","preventionTips":["Confirm metadataServiceUri and ledgers root before startup","Run the metadata format/initialization step once for the cluster","Log and inspect the wrapped IOException cause, not just the code"],"tags":["metadata-store","bookkeeper","initialization"],"backgroundTag":"metadata-service-unavailable","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}