{"record":{"id":"54214f05c8fa74ae","repo":"apache/pulsar","slug":"failed-to-get-children-of-path","errorCode":null,"errorMessage":"Failed to get children of ${path}","messagePattern":"Failed to get children of (.+?)","errorType":"exception","errorClass":"MetadataStoreException","httpStatus":null,"severity":"error","filePath":"pulsar-broker-common/src/main/java/org/apache/pulsar/broker/resources/BaseResources.java","lineNumber":91,"sourceCode":"    public BaseResources(MetadataStore store, TypeReference<T> typeRef, int operationTimeoutSec) {\n        this.store = store;\n        this.cache = store.getMetadataCache(typeRef, MetadataCacheConfig.builder()\n                .retryBackoff(Backoff.builder()\n                        .initialDelay(Duration.ofMillis(5))\n                        .maxBackoff(Duration.ofSeconds(3))\n                        .mandatoryStop(Duration.ofSeconds(operationTimeoutSec)))\n                .build());\n        this.operationTimeoutSec = operationTimeoutSec;\n    }\n\n    protected List<String> getChildren(String path) throws MetadataStoreException {\n        try {\n            return getChildrenAsync(path).get(operationTimeoutSec, TimeUnit.SECONDS);\n        } catch (ExecutionException e) {\n            throw (e.getCause() instanceof MetadataStoreException) ? (MetadataStoreException) e.getCause()\n                    : new MetadataStoreException(e.getCause());\n        } catch (Exception e) {\n            throw new MetadataStoreException(\"Failed to get children of \" + path, e);\n        }\n    }\n\n    protected CompletableFuture<List<String>> getChildrenAsync(String path) {\n        return cache.getChildren(path);\n    }\n\n    protected CompletableFuture<List<String>> getChildrenRecursiveAsync(String path) {\n        Set<String> children = ConcurrentHashMap.newKeySet();\n        CompletableFuture<List<String>> result = new CompletableFuture<>();\n        getChildrenRecursiveAsync(path, children, result, new AtomicInteger(1), path);\n        return result;\n    }\n\n    private void getChildrenRecursiveAsync(String path, Set<String> children, CompletableFuture<List<String>> result,\n            AtomicInteger totalResults, String parent) {\n        cache.getChildren(path).thenAccept(childList -> {\n            childList = childList != null ? childList : Collections.emptyList();","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/resources/BaseResources.java#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check metadata store health (ZooKeeper ensemble status, session expiry in broker logs)","Increase operationTimeoutSec in the metadata store configuration","Retry the operation after transient network issues resolve","Inspect the wrapped cause (e.getCause()) for the underlying store error"],"exampleFix":"// before\nList<String> children = resources.getChildren(path); // may throw\n// after\ntry {\n    List<String> children = resources.getChildren(path);\n} catch (MetadataStoreException e) {\n    log.error(\"Failed to list children of {}\", path, e.getCause());\n    throw new PulsarServerException(\"Metadata store listing failed for \" + path, e.getCause());\n}","handlingStrategy":"retry","validationCode":"// check store reachability first\nMetadataStore store = ...;\nif (!store.getSessionId().isDone() || storeClosed) throw new IllegalStateException(\"metadata store unavailable\");","typeGuard":null,"tryCatchPattern":"try { children = resources.getChildren(path); }\ncatch (MetadataStoreException e) {\n    if (isTransient(e.getCause())) { /* retry with backoff */ }\n    else throw e;\n}","preventionTips":["Monitor metadata store (ZooKeeper) health and session expiry","Set a realistic operationTimeoutSec","Keep child counts per path bounded"],"tags":["metadata-store","zookeeper","timeout","exception-wrapping"],"backgroundTag":"metadata-store-operation-failed","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}