apache/pulsar · critical · RuntimeException

failed initialized

Error message

 failed initialized

What it means

IsolatedBookieEnsemblePlacementPolicy.initialize obtains the metadata store via BookieRackAffinityMapping.getMetadataStore(conf); on MetadataException it throws RuntimeException "... failed initialized", aborting policy initialization because rack data cannot be loaded without the store.

Source

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

     */
    @Getter
    @VisibleForTesting
    private volatile CompletableFuture<Void> initialRackConfigurationLoadFuture =
            CompletableFuture.completedFuture(null);

    public IsolatedBookieEnsemblePlacementPolicy() {
        super();
    }

    @Override
    public RackawareEnsemblePlacementPolicyImpl initialize(ClientConfiguration conf,
            Optional<DNSToSwitchMapping> optionalDnsResolver, HashedWheelTimer timer, FeatureProvider featureProvider,
            StatsLogger statsLogger, BookieAddressResolver bookieAddressResolver) {
        MetadataStore store;
        try {
            store = BookieRackAffinityMapping.getMetadataStore(conf);
        } catch (MetadataException e) {
            throw new RuntimeException(METADATA_STORE_INSTANCE + " failed initialized");
        }
        Set<String> primaryIsolationGroups = new HashSet<>();
        Set<String> secondaryIsolationGroups = new HashSet<>();
        if (conf.getProperty(ISOLATION_BOOKIE_GROUPS) != null) {
            String isolationGroupsString = ConfigurationStringUtil
                    .castToString(conf.getProperty(ISOLATION_BOOKIE_GROUPS));
            if (!isolationGroupsString.isEmpty()) {
                Collections.addAll(primaryIsolationGroups, isolationGroupsString.split(","));
            }
            // Only add the bookieMappingCache if we have defined an isolation group
            bookieMappingCache = store.getMetadataCache(BookiesRackConfiguration.class);
            CompletableFuture<Void> rackConfigurationLoad = bookieMappingCache
                    .get(BookieRackAffinityMapping.BOOKIE_INFO_ROOT_PATH).thenAccept(opt -> opt.ifPresent(
                            bookiesRackConfiguration -> cachedRackConfiguration = bookiesRackConfiguration));
            // Initialization continues when the load fails; isolation is simply not applied until a later refresh.
            rackConfigurationLoad.exceptionally(e -> {
                log.warn().exception(e)
                        .log("Failed to load bookies rack configuration while initialize the PlacementPolicy.");

View on GitHub (pinned to 820761864e)

Solutions

1. Ensure the metadata store URI in the BK client config is valid and reachable before starting the broker
2. Inspect the underlying MetadataException stack trace for connection vs. parsing issues
3. In tests, inject a METADATA_STORE_INSTANCE (e.g. MockMetadataStore) instead of relying on a live service

Example fix

// before
conf.setProperty(ISOLATION_BOOKIE_GROUPS, "group-a"); // no metadata source
// after
conf.setProperty("metadataServiceUri", "metadata-store:zk:zk1:2181/ledgers");
conf.setProperty(ISOLATION_BOOKIE_GROUPS, "group-a");

try {
    policy.initialize(conf, optionalDnsResolver, timer, featureProvider, statsLogger, bookieAddressResolver);
} catch (RuntimeException e) {
    log.error("isolation policy init failed: check metadata store", e);
}

When it happens

Trigger: Ensemble placement policy initialization with a BookKeeper configuration whose metadata service is unreachable or misconfigured (same root cause as the mapping's init failure).

Common situations: Broker starting against an unavailable ZooKeeper; misconfigured metadataServiceUri when using bookkeeper rack awareness; CI/test environments without a metadata backend.

Related errors

• failed to init BookieId list
• METADATA_SERVICE_ERROR
• ${name} failed to fill existing items in ${secs} secs. Fille
• Metadata store address argument is required (--metadata-stor
• Failed to validate global cluster configuration

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