apache/pulsar · error · BookieException.MetadataStoreException

Failed to get cluster instance id

Error message

Failed to get cluster instance id

What it means

Thrown by PulsarRegistrationManager.getClusterInstanceId when reading the instanceid znode under the ledgers root fails — the async store.get either errored (ExecutionException), was interrupted, or exceeded BLOCKING_CALL_TIMEOUT. It is wrapped in BookieException.MetadataStoreException. BookKeeper uses this value during bookie registration to verify all bookies belong to the same cluster, so registration cannot proceed without it.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/bookkeeper/PulsarRegistrationManager.java:128

            }
        }
        try {
            coordinationService.close();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public String getClusterInstanceId() throws BookieException {
        try {
            return store.get(ledgersRootPath + "/" + INSTANCEID)
                    .get(BLOCKING_CALL_TIMEOUT, MILLISECONDS)
                    .map(res -> new String(res.getValue(), UTF_8))
                    .orElseThrow(
                            () -> new BookieException.MetadataStoreException("BookKeeper cluster not initialized"));
        } catch (ExecutionException | InterruptedException | TimeoutException e) {
            throw new BookieException.MetadataStoreException("Failed to get cluster instance id", e);
        }
    }

    @Override
    public void registerBookie(BookieId bookieId, boolean readOnly, BookieServiceInfo bookieServiceInfo)
            throws BookieException {
        String regPath = bookieRegistrationPath + "/" + bookieId;
        String regPathReadOnly = bookieReadonlyRegistrationPath + "/" + bookieId;
        log.info().attr("bookieId", bookieId).attr("readOnly", readOnly).attr("info", bookieServiceInfo)
                .log("RegisterBookie");

        try {
            if (readOnly) {
                ResourceLock<BookieServiceInfo> rwRegistration = bookieRegistration.remove(bookieId);
                if (rwRegistration != null) {
                    log.info().attr("bookieId", bookieId)
                            .log("Bookie was already registered as writable, unregistering");
                    rwRegistration.release().get(BLOCKING_CALL_TIMEOUT, MILLISECONDS);

View on GitHub (pinned to 820761864e)

Solutions

1. Verify the metadata store is healthy and reachable from the bookie (zkCli or pulsar metadata tool) and fix connectivity/quorum issues.
2. Check metadataServiceUrl in bookie.conf points at the correct ZooKeeper/metadata service and ledgers root.
3. Restart the bookie after the metadata store recovers — registration is retried on bookie restart.
4. If timeouts are frequent, check ensemble load and latency; ensure the INSTANCEID znode exists (cluster initialized via bin/bookkeeper shell init).

Example fix

// before
// bookie.conf: metadataServiceUrl=zk+host:2181/ledgers  (wrong host)
// after
// bookie.conf: metadataServiceUrl=zk+zk1:2181,zk2:2181,zk3:2181/ledgers
// plus readiness gate before starting the bookie
// while !nc -z zk1 2181; do sleep 2; done; bin/pulsar bookie start

// before bookie startup: verify store reachable and cluster initialized
MetadataStore store = PulsarMetadataStore.instance(metadataServiceUrl);
boolean ready = store.get(ledgersRootPath + "/instanceid")
        .get(30, TimeUnit.SECONDS).isPresent();
if (!ready) throw new IllegalStateException("Cluster not initialized: run 'bin/bookkeeper shell initbookie' first");

try {
    return registrationManager.getClusterInstanceId();
} catch (BookieException.MetadataStoreException e) {
    if (e.getCause() instanceof TimeoutException || e.getCause() instanceof ExecutionException) {
        return retryWithBackoff(registrationManager::getClusterInstanceId, 3); // transient store outage
    }
    throw e;
}

When it happens

Trigger: Calling getClusterInstanceId() (during bookie startup/registration) when the metadata store is unreachable, the read times out, or the calling thread is interrupted while waiting on the INSTANCEID znode read.

Common situations: Bookie starting before ZooKeeper/metadata service is available; wrong metadataServiceUrl in bookie.conf; ZooKeeper quorum loss or session expiry; network firewall/DNS issues on the bookie host; cluster not fully initialized so instanceid is missing entirely (a distinct sibling error, 'BookKeeper cluster not initialized').

Related errors

• Failed to get children of ${path}
• Failed to check exist ${POLICIES_READONLY_FLAG_PATH}
• Error preloading next range
• Error when get child nodes from zk
• Error contacting with metadata store

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