{"record":{"id":"a24e1e0e348b0d20","repo":"apache/pulsar","slug":"failed-to-start-zookeeper-e-getmessage","errorCode":null,"errorMessage":"Failed to start zookeeper :${e.getMessage()}","messagePattern":"Failed to start zookeeper :(.+?)","errorType":"exception","errorClass":"PulsarServerException","httpStatus":null,"severity":"critical","filePath":"pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/BrokerDiscoveryProvider.java","lineNumber":66,"sourceCode":"    final MetadataStoreCacheLoader metadataStoreCacheLoader;\n    final PulsarResources pulsarResources;\n\n    private final AtomicInteger counter = new AtomicInteger();\n\n    private final OrderedScheduler orderedExecutor = OrderedScheduler.newSchedulerBuilder().numThreads(4)\n            .name(\"pulsar-proxy-ordered\").build();\n    private final ScheduledExecutorService scheduledExecutorScheduler = Executors.newScheduledThreadPool(4,\n            new DefaultThreadFactory(\"pulsar-proxy-scheduled-executor\"));\n\n    public BrokerDiscoveryProvider(ProxyConfiguration config, PulsarResources pulsarResources)\n            throws PulsarServerException {\n        try {\n            this.pulsarResources = pulsarResources;\n            this.metadataStoreCacheLoader = new MetadataStoreCacheLoader(pulsarResources,\n                    config.getMetadataStoreSessionTimeoutMillis());\n        } catch (Exception e) {\n            log.error().exception(e).log(\"Failed to start ZooKeeper\");\n            throw new PulsarServerException(\"Failed to start zookeeper :\" + e.getMessage(), e);\n        }\n    }\n\n    /**\n     * Access the list of available brokers.\n     * Used by Protocol Handlers\n     * @return the list of available brokers\n     * @throws PulsarServerException\n     */\n    public List<? extends ServiceLookupData> getAvailableBrokers() throws PulsarServerException {\n        return metadataStoreCacheLoader.getAvailableBrokers();\n    }\n\n    /**\n     * Find next broker {@link LoadManagerReport} in round-robin fashion.\n     *\n     * @return\n     * @throws PulsarServerException","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/BrokerDiscoveryProvider.java#L48-L84","documentation":"BrokerDiscoveryProvider's constructor wraps any exception from initializing the metadata store (historically ZooKeeper) and its cache loader into a PulsarServerException. The proxy's discovery provider cannot reach or initialize the metadata backend, so discovery is unavailable and the proxy fails to start.","triggerScenarios":"Creating a new BrokerDiscoveryProvider at proxy startup when MetadataStoreCacheLoader construction fails: unreachable ZooKeeper/metadata store URL, connection/auth errors, or invalid metadataStoreUrl configuration.","commonSituations":"ZooKeeper cluster down or under load; wrong zookeeperServers/metadataStoreUrl in proxy config; network/firewall blocking 2181; TLS or auth credentials misconfigured; DNS resolution failure in containerized deployments.","solutions":["Check the log's 'Failed to start ZooKeeper' line with the root exception and verify ZooKeeper/metadata store is reachable (nc/zkCli to the host:2181)","Correct metadataStoreUrl / zookeeperServers in the proxy configuration","Verify network, DNS, firewall, and any TLS/ACL credentials between proxy and metadata store","Restart the proxy after the metadata store cluster is healthy"],"exampleFix":"// before (proxy.conf)\nmetadataStoreUrl=zk:zk-1:2181,zk-2:2181\n// after: fix hostname/port and retry\nmetadataStoreUrl=zk:zk-1.example.com:2181,zk-2.example.com:2181","handlingStrategy":"retry","validationCode":"// Pre-flight metadata store connectivity before creating BrokerDiscoveryProvider\ntry (MetadataStore ms = MetadataStoreFactory.create(conf.getMetadataStoreUrl(), ...)) {\n    ms.get(\"/admin/clusters\").get(30, TimeUnit.SECONDS); // must respond\n}","typeGuard":null,"tryCatchPattern":"try { new BrokerDiscoveryProvider(config, pulsarResources); } catch (PulsarServerException e) { log.error(\"Metadata store init failed: {}\", e.getMessage(), e); // backoff and retry before giving up\n }","preventionTips":["Monitor ZooKeeper/metadata store health and alert before proxy restarts","Validate metadataStoreUrl and credentials in a startup pre-flight","Use stable DNS names and keep-alive sessions in container deployments"],"tags":["zookeeper","metadata-store","pulsar-proxy","startup"],"backgroundTag":"zookeeper-connection-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}