apache/pulsar · critical · RuntimeException

Initialize distributed log for packages management service f

Error message

Initialize distributed log for packages management service failed.

What it means

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.

Source

Thrown at pulsar-package-management/bookkeeper-storage/src/main/java/org/apache/pulsar/packages/management/storage/bookkeeper/BookKeeperPackagesStorage.java:90

                configuration.getBookkeeperClientAuthenticationPlugin());
            if (!Strings.isNullOrEmpty(configuration.getBookkeeperClientAuthenticationParametersName())) {
                conf.setProperty("bkc." + configuration.getBookkeeperClientAuthenticationParametersName(),
                    configuration.getBookkeeperClientAuthenticationParameters());
            }
        }
        // Map arbitrary bookkeeper client configuration into DLog Config. Note that this only configures the
        // bookie client.
        PropertiesUtils.filterAndMapProperties(configuration.getProperties(), "bookkeeper_", "bkc.")
                .forEach((key, value) -> {
                    log.info().attr("key", key).attr("value", value)
                            .log("Applying DLog BookKeeper client configuration setting");
                    conf.setProperty(key, value);
                });
        try {
            this.namespace = NamespaceBuilder.newBuilder()
                .conf(conf).clientId(NS_CLIENT_ID).uri(initializeDlogNamespace()).build();
        } catch (IOException e) {
            throw new RuntimeException("Initialize distributed log for packages management service failed.", e);
        }
        log.info("Packages management bookKeeper storage initialized successfully");
    }

    private URI initializeDlogNamespace() throws IOException {
        String bookkeeperMetadataServiceUri = configuration.getProperty("bookkeeperMetadataServiceUri");
        String ledgersRootPath;
        String ledgersStoreServers;
        if (StringUtils.isNotBlank(bookkeeperMetadataServiceUri)) {
            URI metadataServiceUri = URI.create(bookkeeperMetadataServiceUri);
            ledgersStoreServers = metadataServiceUri.getAuthority().replace(";", ",");
            ledgersRootPath = metadataServiceUri.getPath();
        } else {
            ledgersRootPath = configuration.getPackagesManagementLedgerRootPath();
            if (StringUtils.isNotBlank(configuration.getMetadataStoreUrl())) {
                ledgersStoreServers = configuration.getMetadataStoreUrl();
                if (ledgersStoreServers.startsWith(ZK_SCHEME_IDENTIFIER)) {
                    ledgersStoreServers = ledgersStoreServers.substring(ZK_SCHEME_IDENTIFIER.length());

View on GitHub (pinned to 820761864e)

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.

Example fix

// before
bookkeeperMetadataServiceUri=bk://zk-broken:2181/ledgers
// after
bookkeeperMetadataServiceUri=bk://zk1:2181/ledgers

Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: verify BK metadata service URI is reachable
String uri = configuration.getProperty("bookkeeperMetadataServiceUri");
if (uri == null || !uri.startsWith("bk://")) {
    throw new IllegalStateException("bookkeeperMetadataServiceUri missing or malformed");
}

Try / catch

try {
    packagesStorage.initialize(conf);
} catch (RuntimeException e) {
    Throwable root = e.getCause();
    log.error("DLog namespace init failed; check BookKeeper/ZK health and bookkeeperMetadataServiceUri", root);
    throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: Misconfigured bookkeeperMetadataServiceUri property (e.g. 'bk://host:2181/ledgers' pointing to an unavailable BK metadata store), BookKeeper cluster down, or wrong namespace path permissions.

Related errors

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