apache/pulsar · error · MetadataStoreException

Failed to check exist ${path}

Error message

Failed to check exist ${path}

What it means

BaseResources.exists checks node presence synchronously; unexpected causes, timeout, or interruption are wrapped as MetadataStoreException('Failed to check exist <path>'). It means the existence probe itself failed, not that the node is absent — absence returns false without throwing.

Source

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

            } else if (ex != null) {
                log.info().attr("path", path).exception(ex).log("Failed to delete path from metadata store");
                future.completeExceptionally(ex);
            } else {
                log.info().attr("path", path).log("Deleted path from metadata store");
                future.complete(null);
            }
        });
        return future;
    }

    protected boolean exists(String path) throws MetadataStoreException {
        try {
            return cache.exists(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 check exist " + path, e);
        }
    }

    protected CompletableFuture<Boolean> existsAsync(String path) {
        return cache.exists(path);
    }

    public int getOperationTimeoutSec() {
        return operationTimeoutSec;
    }

    protected static String joinPath(String... parts) {
        StringBuilder sb = new StringBuilder();
        Joiner.on('/').appendTo(sb, parts);
        return sb.toString();
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Check metadata store connectivity and session health in broker logs
2. Retry the existence check after transient failures
3. Increase operationTimeoutSec
4. Distinguish false (node absent) from thrown exception (check failed) in caller logic

Example fix

// before
if (resources.exists(path)) { ... }
// after
boolean exists;
try { exists = resources.exists(path); }
catch (MetadataStoreException e) {
    throw new PulsarServerException("Existence check failed for " + path, e.getCause());
}
if (exists) { ... }

// verify store reachable before probing
if (!metadataStoreReachable()) throw new IllegalStateException("Metadata store unreachable");

try { exists = resources.exists(path); }
catch (MetadataStoreException e) {
    // existence check failed ≠ node absent
    throw new PulsarServerException("exists() check failed for " + path, e.getCause());
}

When it happens

Trigger: Calling exists(path) when the metadata store connection fails, the operation exceeds operationTimeoutSec, or the blocking get is interrupted.

Common situations: Metadata store outage or session expiry; transient network blips during existence checks before create/delete; misconfigured metadata store URL; too-short timeout under load.

Related errors

• Failed to get children of ${path}
• Failed to get data from ${path}
• RestException(e)
• Time-out while checking authorization
• Failed to validate global cluster configuration : ns=%s ems

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