apache/pulsar · critical · PulsarServerException

Failed to start zookeeper

Error message

Failed to start zookeeper :${e.getMessage()}

What it means

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.

Solutions

1. 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)
2. Correct metadataStoreUrl / zookeeperServers in the proxy configuration
3. Verify network, DNS, firewall, and any TLS/ACL credentials between proxy and metadata store
4. Restart the proxy after the metadata store cluster is healthy

Example fix

// before (proxy.conf)
metadataStoreUrl=zk:zk-1:2181,zk-2:2181
// after: fix hostname/port and retry
metadataStoreUrl=zk:zk-1.example.com:2181,zk-2.example.com:2181

// Pre-flight metadata store connectivity before creating BrokerDiscoveryProvider
try (MetadataStore ms = MetadataStoreFactory.create(conf.getMetadataStoreUrl(), ...)) {
    ms.get("/admin/clusters").get(30, TimeUnit.SECONDS); // must respond
}

try { new BrokerDiscoveryProvider(config, pulsarResources); } catch (PulsarServerException e) { log.error("Metadata store init failed: {}", e.getMessage(), e); // backoff and retry before giving up
 }

When it happens

Trigger: Creating a new BrokerDiscoveryProvider at proxy startup when MetadataStoreCacheLoader construction fails: unreachable ZooKeeper/metadata store URL, connection/auth errors, or invalid metadataStoreUrl configuration.

Common situations: 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.

Related errors

• Failed to refresh self owner info.
• Error contacting metadata store
• Error contacting with metadata store
• Error contacting zookeeper
• Error preloading next range

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

Appendix: source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/BrokerDiscoveryProvider.java:66

    final MetadataStoreCacheLoader metadataStoreCacheLoader;
    final PulsarResources pulsarResources;

    private final AtomicInteger counter = new AtomicInteger();

    private final OrderedScheduler orderedExecutor = OrderedScheduler.newSchedulerBuilder().numThreads(4)
            .name("pulsar-proxy-ordered").build();
    private final ScheduledExecutorService scheduledExecutorScheduler = Executors.newScheduledThreadPool(4,
            new DefaultThreadFactory("pulsar-proxy-scheduled-executor"));

    public BrokerDiscoveryProvider(ProxyConfiguration config, PulsarResources pulsarResources)
            throws PulsarServerException {
        try {
            this.pulsarResources = pulsarResources;
            this.metadataStoreCacheLoader = new MetadataStoreCacheLoader(pulsarResources,
                    config.getMetadataStoreSessionTimeoutMillis());
        } catch (Exception e) {
            log.error().exception(e).log("Failed to start ZooKeeper");
            throw new PulsarServerException("Failed to start zookeeper :" + e.getMessage(), e);
        }
    }

    /**
     * Access the list of available brokers.
     * Used by Protocol Handlers
     * @return the list of available brokers
     * @throws PulsarServerException
     */
    public List<? extends ServiceLookupData> getAvailableBrokers() throws PulsarServerException {
        return metadataStoreCacheLoader.getAvailableBrokers();
    }

    /**
     * Find next broker {@link LoadManagerReport} in round-robin fashion.
     *
     * @return
     * @throws PulsarServerException

View on GitHub (pinned to 820761864e)