apache/pulsar · error · MetadataStoreException

Failed to create ${path}

Error message

Failed to create ${path}

What it means

BaseResources.create writes new data to a metadata path and blocks; failures other than a plain MetadataStoreException cause (plus timeout/interruption) are wrapped as MetadataStoreException('Failed to create <path>'). Commonly the underlying cause is a node-already-exists error from the store.

Source

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

            throw (e.getCause() instanceof MetadataStoreException) ? (MetadataStoreException) e.getCause()
                    : new MetadataStoreException(e.getCause());
        } catch (Exception e) {
            throw new MetadataStoreException("Failed to set/create " + path, e);
        }
    }

    protected CompletableFuture<Void> setWithCreateAsync(String path, Function<Optional<T>, T> createFunction) {
        return cache.readModifyUpdateOrCreate(path, createFunction).thenApply(__ -> null);
    }

    protected void create(String path, T data) throws MetadataStoreException {
        try {
            createAsync(path, data).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 create " + path, e);
        }
    }

    protected CompletableFuture<Void> createAsync(String path, T data) {
        return cache.create(path, data);
    }

    protected void delete(String path) throws MetadataStoreException {
        try {
            deleteAsync(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 delete " + path, e);
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Check if the node already exists (exists()) and use set/setWithCreate instead of create
2. Handle MetadataStoreException.AlreadyExists cause explicitly
3. Verify metadata store write access and health
4. Increase operationTimeoutSec if timeouts are the cause

Example fix

// before
resources.create(path, data);
// after
if (!resources.exists(path)) {
    try { resources.create(path, data); }
    catch (MetadataStoreException e) {
        if (!(e.getCause() instanceof MetadataStoreException.AlreadyExistsException)) throw e;
    }
}

if (resources.exists(path)) throw new IllegalStateException("Node already exists: " + path);

try { resources.create(path, data); }
catch (MetadataStoreException e) {
    if (e.getCause() instanceof MetadataStoreException.AlreadyExistsException) { /* idempotent handling */ }
    else throw e;
}

When it happens

Trigger: Calling create(path, data) when the path already exists, the store rejects the write, the operation times out, or the thread is interrupted.

Common situations: Double creation of a tenant/namespace/cluster resource by concurrent admin requests; store read-only; session expired; timeout under load.

Related errors

• Failed to set/create ${path}
• Failed to get children of ${path}
• Failed to get data from ${path}
• Failed to set data for ${path}
• Failed to delete ${path}

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