apache/pulsar · critical · PulsarServerException

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

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.

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)

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.
• Metadata store address argument is required (--metadata-stor
• Interrupted when connecting to zookeeper server
• Neither METADATA_STORE_INSTANCE configuration set in the BK
• failed to init BookieId list

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