apache/pulsar · error · MetadataStoreException

Failed to get children of ${path}

Error message

Failed to get children of ${path}

What it means

BaseResources.getChildren wraps the async metadata-store children lookup and converts any non-MetadataStoreException failure (timeout, interruption, unexpected cause) into MetadataStoreException with the message 'Failed to get children of <path>'. It indicates the synchronous get(operationTimeoutSec) timed out or the store call failed while listing children of a metadata path.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/resources/BaseResources.java:91

    public BaseResources(MetadataStore store, TypeReference<T> typeRef, int operationTimeoutSec) {
        this.store = store;
        this.cache = store.getMetadataCache(typeRef, MetadataCacheConfig.builder()
                .retryBackoff(Backoff.builder()
                        .initialDelay(Duration.ofMillis(5))
                        .maxBackoff(Duration.ofSeconds(3))
                        .mandatoryStop(Duration.ofSeconds(operationTimeoutSec)))
                .build());
        this.operationTimeoutSec = operationTimeoutSec;
    }

    protected List<String> getChildren(String path) throws MetadataStoreException {
        try {
            return getChildrenAsync(path).get(operationTimeoutSec, 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 get children of " + path, e);
        }
    }

    protected CompletableFuture<List<String>> getChildrenAsync(String path) {
        return cache.getChildren(path);
    }

    protected CompletableFuture<List<String>> getChildrenRecursiveAsync(String path) {
        Set<String> children = ConcurrentHashMap.newKeySet();
        CompletableFuture<List<String>> result = new CompletableFuture<>();
        getChildrenRecursiveAsync(path, children, result, new AtomicInteger(1), path);
        return result;
    }

    private void getChildrenRecursiveAsync(String path, Set<String> children, CompletableFuture<List<String>> result,
            AtomicInteger totalResults, String parent) {
        cache.getChildren(path).thenAccept(childList -> {
            childList = childList != null ? childList : Collections.emptyList();

View on GitHub (pinned to 820761864e)

Solutions

1. Check metadata store health (ZooKeeper ensemble status, session expiry in broker logs)
2. Increase operationTimeoutSec in the metadata store configuration
3. Retry the operation after transient network issues resolve
4. Inspect the wrapped cause (e.getCause()) for the underlying store error

Example fix

// before
List<String> children = resources.getChildren(path); // may throw
// after
try {
    List<String> children = resources.getChildren(path);
} catch (MetadataStoreException e) {
    log.error("Failed to list children of {}", path, e.getCause());
    throw new PulsarServerException("Metadata store listing failed for " + path, e.getCause());
}

// check store reachability first
MetadataStore store = ...;
if (!store.getSessionId().isDone() || storeClosed) throw new IllegalStateException("metadata store unavailable");

try { children = resources.getChildren(path); }
catch (MetadataStoreException e) {
    if (isTransient(e.getCause())) { /* retry with backoff */ }
    else throw e;
}

When it happens

Trigger: Calling getChildren(path) when the metadata store (ZooKeeper/etcd/RocksDB) errors, when the operation exceeds operationTimeoutSec, or when the thread is interrupted while blocking on the future.

Common situations: ZooKeeper session expired / ensemble unreachable; operation timeout too small for slow clusters; path with an enormous number of children causing slow listing; network partition between broker and metadata store.

Related errors

• Failed to get data from ${path}
• Failed to check exist ${path}
• Failed to check exist ${POLICIES_READONLY_FLAG_PATH}
• Error preloading next range
• Error when get child nodes from zk

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