{"record":{"id":"8fde71c452821fc2","repo":"apache/pulsar","slug":"initialize-distributed-log-for-packages-management","errorCode":null,"errorMessage":"Initialize distributed log for packages management service failed.","messagePattern":"Initialize distributed log for packages management service failed\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"pulsar-package-management/bookkeeper-storage/src/main/java/org/apache/pulsar/packages/management/storage/bookkeeper/BookKeeperPackagesStorage.java","lineNumber":90,"sourceCode":"                configuration.getBookkeeperClientAuthenticationPlugin());\n            if (!Strings.isNullOrEmpty(configuration.getBookkeeperClientAuthenticationParametersName())) {\n                conf.setProperty(\"bkc.\" + configuration.getBookkeeperClientAuthenticationParametersName(),\n                    configuration.getBookkeeperClientAuthenticationParameters());\n            }\n        }\n        // Map arbitrary bookkeeper client configuration into DLog Config. Note that this only configures the\n        // bookie client.\n        PropertiesUtils.filterAndMapProperties(configuration.getProperties(), \"bookkeeper_\", \"bkc.\")\n                .forEach((key, value) -> {\n                    log.info().attr(\"key\", key).attr(\"value\", value)\n                            .log(\"Applying DLog BookKeeper client configuration setting\");\n                    conf.setProperty(key, value);\n                });\n        try {\n            this.namespace = NamespaceBuilder.newBuilder()\n                .conf(conf).clientId(NS_CLIENT_ID).uri(initializeDlogNamespace()).build();\n        } catch (IOException e) {\n            throw new RuntimeException(\"Initialize distributed log for packages management service failed.\", e);\n        }\n        log.info(\"Packages management bookKeeper storage initialized successfully\");\n    }\n\n    private URI initializeDlogNamespace() throws IOException {\n        String bookkeeperMetadataServiceUri = configuration.getProperty(\"bookkeeperMetadataServiceUri\");\n        String ledgersRootPath;\n        String ledgersStoreServers;\n        if (StringUtils.isNotBlank(bookkeeperMetadataServiceUri)) {\n            URI metadataServiceUri = URI.create(bookkeeperMetadataServiceUri);\n            ledgersStoreServers = metadataServiceUri.getAuthority().replace(\";\", \",\");\n            ledgersRootPath = metadataServiceUri.getPath();\n        } else {\n            ledgersRootPath = configuration.getPackagesManagementLedgerRootPath();\n            if (StringUtils.isNotBlank(configuration.getMetadataStoreUrl())) {\n                ledgersStoreServers = configuration.getMetadataStoreUrl();\n                if (ledgersStoreServers.startsWith(ZK_SCHEME_IDENTIFIER)) {\n                    ledgersStoreServers = ledgersStoreServers.substring(ZK_SCHEME_IDENTIFIER.length());","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-package-management/bookkeeper-storage/src/main/java/org/apache/pulsar/packages/management/storage/bookkeeper/BookKeeperPackagesStorage.java#L72-L108","documentation":"RuntimeException thrown by BookKeeperPackagesStorage.initialize when building the DistributedLog namespace for the packages management service fails (IOException from NamespaceBuilder/initializeDlogNamespace). The packages storage cannot start without its DLog namespace.","triggerScenarios":"Starting the packages management storage when the bookkeeper metadata service URI is wrong/unreachable, or DistributedLog cannot create/read the namespace at the configured dlog namespace path.","commonSituations":"Misconfigured bookkeeperMetadataServiceUri property (e.g. 'bk://host:2181/ledgers' pointing to an unavailable BK metadata store), BookKeeper cluster down, or wrong namespace path permissions.","solutions":["Verify the bookkeeperMetadataServiceUri configuration property is correct and reachable from this host.","Ensure BookKeeper and its metadata store (ZooKeeper) are running and healthy.","Check that the DLog namespace path exists or can be created with proper permissions.","Inspect the wrapped IOException cause in the stack trace for the root network/ZK failure and fix that first."],"exampleFix":"// before\nbookkeeperMetadataServiceUri=bk://zk-broken:2181/ledgers\n// after\nbookkeeperMetadataServiceUri=bk://zk1:2181/ledgers","handlingStrategy":"try-catch","validationCode":"// preflight: verify BK metadata service URI is reachable\nString uri = configuration.getProperty(\"bookkeeperMetadataServiceUri\");\nif (uri == null || !uri.startsWith(\"bk://\")) {\n    throw new IllegalStateException(\"bookkeeperMetadataServiceUri missing or malformed\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    packagesStorage.initialize(conf);\n} catch (RuntimeException e) {\n    Throwable root = e.getCause();\n    log.error(\"DLog namespace init failed; check BookKeeper/ZK health and bookkeeperMetadataServiceUri\", root);\n    throw e;\n}","preventionTips":["Verify BookKeeper and its metadata store are healthy before deploying the packages service.","Validate bookkeeperMetadataServiceUri in startup health checks.","Ensure network/firewall rules allow connectivity to the BK metadata service.","Check DLog namespace path permissions in ZooKeeper."],"tags":["bookkeeper","distributedlog","initialization","configuration"],"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"}