apache/pulsar · error · MetadataStoreException

Failed to set/create ${path}

Error message

Failed to set/create ${path}

What it means

BaseResources.setWithCreate uses cache.readModifyUpdateOrCreate to update existing data or create it if missing; any failure (store error, timeout, interruption, unexpected cause) surfaces as MetadataStoreException('Failed to set/create <path>'). It means the create-or-update of the resource could not complete.

Source

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

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

    protected CompletableFuture<Void> setAsync(String path, Function<T, T> modifyFunction) {
        return cache.readModifyUpdate(path, modifyFunction).thenApply(__ -> null);
    }

    protected void setWithCreate(String path, Function<Optional<T>, T> createFunction) throws MetadataStoreException {
        try {
            setWithCreateAsync(path, createFunction).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 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);
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Retry; if the node now exists, fall back to set (update) semantics
2. Check metadata store write permissions/health
3. Increase operationTimeoutSec
4. Avoid concurrent first-time creation of the same path from multiple clients

Example fix

// before
resources.setWithCreate(path, opt -> new Policies());
// after
try {
    resources.setWithCreate(path, opt -> new Policies());
} catch (MetadataStoreException e) {
    if (e.getCause() != null && e.getCause().getMessage().contains("already exists")) {
        resources.set(path, p -> p); // node created concurrently
    } else { throw e; }
}

boolean exists = resources.exists(path);
// choose set vs setWithCreate based on existence to reduce create conflicts

try { resources.setWithCreate(path, creator); }
catch (MetadataStoreException e) {
    if (causeIndicatesAlreadyExists(e.getCause())) { resources.set(path, Function.identity()); }
    else throw e;
}

When it happens

Trigger: Calling setWithCreate(path, createFunction) when the metadata store update or initial create fails, exceeds operationTimeoutSec, or hits a create conflict because the node appeared concurrently.

Common situations: Two admin clients creating the same resource concurrently; store unavailable; config store in read-only state so create fails; interrupted admin thread.

Related errors

• Failed to set data for ${path}
• Failed to create ${path}
• Concurrent modification
• Failed to get children of ${path}
• Failed to get data from ${path}

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