{"record":{"id":"79ec87c970435e63","repo":"apache/pulsar","slug":"neither-metadata-store-instance-configuration-set","errorCode":null,"errorMessage":"Neither METADATA_STORE_INSTANCE configuration set in the BK client configuration nor metadataServiceUri/zkServers set in bk server configuration","messagePattern":"Neither METADATA_STORE_INSTANCE configuration set in the BK client configuration nor metadataServiceUri/zkServers set in bk server configuration","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"pulsar-broker-common/src/main/java/org/apache/pulsar/bookie/rackawareness/BookieRackAffinityMapping.java","lineNumber":96,"sourceCode":"                throw new RuntimeException(METADATA_STORE_INSTANCE + \" is not an instance of MetadataStore\");\n            }\n            store = (MetadataStore) storeProperty;\n        } else {\n            String url;\n            String metadataServiceUri = ConfigurationStringUtil.castToString(conf.getProperty(\"metadataServiceUri\"));\n            if (StringUtils.isNotBlank(metadataServiceUri)) {\n                try {\n                    url = metadataServiceUri.replaceFirst(METADATA_STORE_SCHEME + \":\", \"\")\n                            .replace(\";\", \",\");\n                } catch (Exception e) {\n                    throw new MetadataException(Code.METADATA_SERVICE_ERROR, e);\n                }\n            } else {\n                String zkServers = ConfigurationStringUtil.castToString(conf.getProperty(\"zkServers\"));\n                if (StringUtils.isBlank(zkServers)) {\n                    String errorMsg = String.format(\"Neither %s configuration set in the BK client configuration nor \"\n                            + \"metadataServiceUri/zkServers set in bk server configuration\", METADATA_STORE_INSTANCE);\n                    throw new RuntimeException(errorMsg);\n                }\n                url = zkServers;\n            }\n            try {\n                int zkTimeout = Integer.parseInt((String) conf.getProperty(\"zkTimeout\"));\n                store = MetadataStoreExtended.create(url,\n                        MetadataStoreConfig.builder()\n                                .metadataStoreName(MetadataStoreConfig.METADATA_STORE)\n                                .sessionTimeoutMillis(zkTimeout)\n                                .build());\n            } catch (MetadataStoreException e) {\n                throw new MetadataException(Code.METADATA_SERVICE_ERROR, e);\n            }\n        }\n        return store;\n    }\n\n    @Override","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker-common/src/main/java/org/apache/pulsar/bookie/rackawareness/BookieRackAffinityMapping.java#L78-L114","documentation":"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.","triggerScenarios":"Running the rack-awareness mapping / isolated placement policy with a BookKeeper Configuration lacking METADATA_STORE_INSTANCE, metadataServiceUri and zkServers keys.","commonSituations":"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.","solutions":["Set metadataServiceUri (e.g. metadataServiceUri=metadata-store:zk:zk1:2181/ledgers) in the broker/BK configuration","Or set zkServers in the BK server configuration","Or inject a METADATA_STORE_INSTANCE programmatically"],"exampleFix":"// before: broker.conf missing both\n// after:\n// metadataServiceUri=metadata-store:zk:zk1:2181/ledgers\n// or bookkeeper config: zkServers=zk1:2181","handlingStrategy":"validation","validationCode":"boolean ok = conf.getProperty(METADATA_STORE_INSTANCE) != null\n    || StringUtils.isNotBlank((String) conf.getProperty(\"metadataServiceUri\"))\n    || StringUtils.isNotBlank((String) conf.getProperty(\"zkServers\"));\nif (!ok) throw new IllegalArgumentException(\"no metadata store source configured\");","typeGuard":null,"tryCatchPattern":"try {\n    mapping.setConf(conf);\n} catch (RuntimeException e) {\n    log.error(\"metadata store source missing\", e);\n    System.exit(1); // fail fast\n}","preventionTips":["Always set metadataServiceUri or zkServers in BK/broker config","Validate config at startup before loading placement policies","Keep config templates updated across version upgrades"],"tags":["configuration","metadata-store","zookeeper","missing-config"],"backgroundTag":"missing-config-key","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"}