apache/pulsar · error · MetadataStoreException

Failed to check exist ${POLICIES_READONLY_FLAG_PATH}

Error message

Failed to check exist ${POLICIES_READONLY_FLAG_PATH}

What it means

MetadataStoreException thrown by NamespaceResources.getPoliciesReadOnly() when the synchronous check for the read-only flag node (/admin/flags/policies-readonly) in the metadata store fails. The async existence check is awaited with .get(timeout); any non-ExecutionException failure — most commonly a TimeoutException from the .get() call, or InterruptedException — is wrapped with this message. It indicates the broker could not determine whether namespace policies are read-only, typically due to metadata store (ZooKeeper/etcd) connectivity or latency problems.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/resources/NamespaceResources.java:83

        partitionedTopicResources = new PartitionedTopicResources(configurationStore, operationTimeoutSec, executor);
    }

    public CompletableFuture<List<String>> listNamespacesAsync(String tenant) {
        return getChildrenRecursiveAsync(joinPath(BASE_POLICIES_PATH, tenant));
    }

    public CompletableFuture<Boolean> getPoliciesReadOnlyAsync() {
        return super.existsAsync(POLICIES_READONLY_FLAG_PATH);
    }

    public boolean getPoliciesReadOnly() throws MetadataStoreException {
        try {
            return getPoliciesReadOnlyAsync().get(getOperationTimeoutSec(), TimeUnit.SECONDS);
        } catch (ExecutionException e) {
            throw (e.getCause() instanceof MetadataStoreException) ? (MetadataStoreException) e.getCause()
                    : new MetadataStoreException(e.getCause());
        } catch (Exception e) {
            throw new MetadataStoreException("Failed to check exist " + POLICIES_READONLY_FLAG_PATH, e);
        }
    }

    public void createPolicies(NamespaceName ns, Policies policies) throws MetadataStoreException{
        create(joinPath(BASE_POLICIES_PATH, ns.toString()), policies);
    }

    public CompletableFuture<Void> createPoliciesAsync(NamespaceName ns, Policies policies) {
        return createAsync(joinPath(BASE_POLICIES_PATH, ns.toString()), policies);
    }

    public boolean namespaceExists(NamespaceName ns) throws MetadataStoreException {
        String path = joinPath(BASE_POLICIES_PATH, ns.toString());
        return super.exists(path) && super.getChildren(path).isEmpty();
    }

    public CompletableFuture<Boolean> namespaceExistsAsync(NamespaceName ns) {
        String path = joinPath(BASE_POLICIES_PATH, ns.toString());

View on GitHub (pinned to 820761864e)

Solutions

1. Check metadata store (ZooKeeper/etcd) health and broker connectivity to it
2. Increase operationTimeoutSec if the store is merely slow
3. Inspect the wrapped cause (getCause()) — TimeoutException vs session-expired — and remediate accordingly
4. Prefer the async getPoliciesReadOnlyAsync() API on non-blocking threads and handle its CompletableFuture failure directly

Example fix

// before
boolean ro = namespaceResources.getPoliciesReadOnly();
// after
boolean ro;
try {
    ro = namespaceResources.getPoliciesReadOnly();
} catch (MetadataStoreException e) {
    log.error("Cannot read policies read-only flag (cause: {}), failing over/retrying", e.getCause(), e);
    throw e;
}

// Pre-check reachability (conceptual)
if (!metadataStoreAdminAvailable(namespaceResources, opTimeoutSec)) {
    throw new IllegalStateException("Metadata store unreachable; cannot read policies read-only flag");
}

try {
    boolean ro = nsResources.getPoliciesReadOnly();
} catch (MetadataStoreException e) {
    if (e.getCause() instanceof TimeoutException) {
        // retry or fail over to another metadata store node
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling getPoliciesReadOnly() when the metadata store is unreachable/slow so getPoliciesReadOnlyAsync().get() times out (getOperationTimeoutSec exceeded), the calling thread is interrupted, or the metadata store session expires mid-operation.

Common situations: Broker startup or admin operations against a ZooKeeper quorum that is overloaded, partitioned, or down; network latency between broker and metadata store exceeding the operation timeout; thread interrupted during broker shutdown while policies are being read.

Related errors

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

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