apache/pulsar · critical · RuntimeException

failed to init BookieId list

Error message

 failed to init BookieId list

What it means

BookieRackAffinityMapping.setConf calls getMetadataStore(conf); if that throws MetadataException (failed to create/connect the metadata store), setConf wraps it in a RuntimeException "... failed to init BookieId list". This makes the mapping fail fast at configuration time instead of silently serving empty rack data.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/bookie/rackawareness/BookieRackAffinityMapping.java:121

                        MetadataStoreConfig.builder()
                                .metadataStoreName(MetadataStoreConfig.METADATA_STORE)
                                .sessionTimeoutMillis(zkTimeout)
                                .build());
            } catch (MetadataStoreException e) {
                throw new MetadataException(Code.METADATA_SERVICE_ERROR, e);
            }
        }
        return store;
    }

    @Override
    public synchronized void setConf(Configuration conf) {
        super.setConf(conf);
        MetadataStore store;
        try {
            store = getMetadataStore(conf);
        } catch (MetadataException e) {
            throw new RuntimeException(METADATA_STORE_INSTANCE + " failed to init BookieId list");
        }

        bookieMappingCache = store.getMetadataCache(BookiesRackConfiguration.class);
        store.registerListener(this::handleUpdates);

        try {
            var racksWithHost = bookieMappingCache.get(BOOKIE_INFO_ROOT_PATH)
                    .thenApply(optRes -> optRes.orElseGet(BookiesRackConfiguration::new))
                    .get();

            for (var bookieMapping : racksWithHost.values()) {
                for (String address : bookieMapping.keySet()) {
                    bookieAddressListLastTime.add(BookieId.parse(address));
                }
                log.debug()
                        .attr("bookieAddressListLastTime", bookieAddressListLastTime)
                        .log("BookieRackAffinityMapping init, bookieAddressListLastTime");
            }

View on GitHub (pinned to 820761864e)

Solutions

1. Check broker logs for the underlying MetadataException and fix the metadata store URL/credentials/connectivity
2. Verify ZooKeeper or etcd is reachable from the broker (telnet the host:port)
3. Validate the metadataServiceUri scheme (metadata-store:zk:... ) and zkTimeout parseability, then restart

Example fix

// before
// metadataServiceUri=metadata-store:zk:zk-bad-host:2181/ledgers
// after
// metadataServiceUri=metadata-store:zk:zk1:2181,zk2:2181,zk3:2181/ledgers

try {
    mapping.setConf(conf);
} catch (RuntimeException e) {
    log.error("failed to init bookie rack mapping", e);
    // check connectivity to the metadata store before retry/startup
}

When it happens

Trigger: setConf() invoked (by BookKeeper loading the RackawareEnsemblePlacementPolicy config) when the metadata service URI is unreachable, malformed, or the store client cannot be created.

Common situations: ZooKeeper down or wrong address in metadataServiceUri; invalid zkTimeout value; network/firewall blocking the metadata store port; bad scheme in metadataStoreUrl during migration to the metadata-store abstraction.

Related errors

• Failed to write cookie for bookie ${bookieId}
• Metadata store address argument is required (--metadata-stor
• Failed to refresh self owner info.
• Neither METADATA_STORE_INSTANCE configuration set in the BK
• failed initialized

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