apache/pulsar · error · RuntimeException

Neither METADATA_STORE_INSTANCE configuration set in the BK

Error message

Neither METADATA_STORE_INSTANCE configuration set in the BK client configuration nor metadataServiceUri/zkServers set in bk server configuration

What it means

getMetadataStore builds a MetadataStore either from METADATA_STORE_INSTANCE, from metadataServiceUri, or from zkServers. If none of these is provided (all blank), it cannot determine a metadata backend and throws a RuntimeException saying neither METADATA_STORE_INSTANCE nor metadataServiceUri/zkServers is set.

Source

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

                throw new RuntimeException(METADATA_STORE_INSTANCE + " is not an instance of MetadataStore");
            }
            store = (MetadataStore) storeProperty;
        } else {
            String url;
            String metadataServiceUri = ConfigurationStringUtil.castToString(conf.getProperty("metadataServiceUri"));
            if (StringUtils.isNotBlank(metadataServiceUri)) {
                try {
                    url = metadataServiceUri.replaceFirst(METADATA_STORE_SCHEME + ":", "")
                            .replace(";", ",");
                } catch (Exception e) {
                    throw new MetadataException(Code.METADATA_SERVICE_ERROR, e);
                }
            } else {
                String zkServers = ConfigurationStringUtil.castToString(conf.getProperty("zkServers"));
                if (StringUtils.isBlank(zkServers)) {
                    String errorMsg = String.format("Neither %s configuration set in the BK client configuration nor "
                            + "metadataServiceUri/zkServers set in bk server configuration", METADATA_STORE_INSTANCE);
                    throw new RuntimeException(errorMsg);
                }
                url = zkServers;
            }
            try {
                int zkTimeout = Integer.parseInt((String) conf.getProperty("zkTimeout"));
                store = MetadataStoreExtended.create(url,
                        MetadataStoreConfig.builder()
                                .metadataStoreName(MetadataStoreConfig.METADATA_STORE)
                                .sessionTimeoutMillis(zkTimeout)
                                .build());
            } catch (MetadataStoreException e) {
                throw new MetadataException(Code.METADATA_SERVICE_ERROR, e);
            }
        }
        return store;
    }

    @Override

View on GitHub (pinned to 820761864e)

Solutions

1. Set metadataServiceUri (e.g. metadataServiceUri=metadata-store:zk:zk1:2181/ledgers) in the broker/BK configuration
2. Or set zkServers in the BK server configuration
3. Or inject a METADATA_STORE_INSTANCE programmatically

Example fix

// before: broker.conf missing both
// after:
// metadataServiceUri=metadata-store:zk:zk1:2181/ledgers
// or bookkeeper config: zkServers=zk1:2181

boolean ok = conf.getProperty(METADATA_STORE_INSTANCE) != null
    || StringUtils.isNotBlank((String) conf.getProperty("metadataServiceUri"))
    || StringUtils.isNotBlank((String) conf.getProperty("zkServers"));
if (!ok) throw new IllegalArgumentException("no metadata store source configured");

try {
    mapping.setConf(conf);
} catch (RuntimeException e) {
    log.error("metadata store source missing", e);
    System.exit(1); // fail fast
}

When it happens

Trigger: Running the rack-awareness mapping / isolated placement policy with a BookKeeper Configuration lacking METADATA_STORE_INSTANCE, metadataServiceUri and zkServers keys.

Common situations: Standalone BK deployment configured only in bookkeeper.conf with non-standard keys; Pulsar proxy/functions worker with partial BK client config; missing metadataServiceUri in broker.conf during upgrades.

Related errors

• Metadata store address argument is required (--metadata-stor
• Failed to refresh self owner info.
• Missing configured value for:
• is not an instance of MetadataStore
• failed to init BookieId list

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