apache/pulsar · error · org.apache.pulsar.broker.admin.RestException

Failed to validate global cluster configuration

Error message

Failed to validate global cluster configuration

What it means

Thrown when the broker cannot verify ownership/configuration of a global (replicated) namespace while processing an admin request. validateGlobalNamespaceOwnership fetches namespace policies; any unexpected exception (e.g. metadata store connectivity problems) is converted into HTTP 503 Service Unavailable. It signals a broker-side/metadata-store problem, not a client request malformedness.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java:232

                    .attr("namespace", namespace)
                    .log("Invalid namespace name");
            throw new RestException(Status.PRECONDITION_FAILED, "Namespace name is not valid");
        }
    }

    protected void validateGlobalNamespaceOwnership() {
        try {
            validateGlobalNamespaceOwnership(this.namespaceName);
        } catch (IllegalArgumentException e) {
            throw new RestException(Status.PRECONDITION_FAILED, "Tenant name or namespace is not valid");
        } catch (RestException re) {
            throw re;
        } catch (Exception e) {
            log.warn()
                    .attr("namespace", namespaceName)
                    .exceptionMessage(e)
                    .log("Failed to validate global cluster configuration");
            throw new RestException(Status.SERVICE_UNAVAILABLE, "Failed to validate global cluster configuration");
        }
    }
    protected void validateTopicName(String tenant, String namespace, String encodedTopic) {
        String topic = Codec.decode(encodedTopic);
        try {
            this.namespaceName = NamespaceName.get(tenant, namespace);
            this.topicName = TopicName.get(domain(), namespaceName, topic);
        } catch (IllegalArgumentException e) {
            log.warn()
                    .attr("domain", domain())
                    .attr("tenant", tenant)
                    .attr("namespace", namespace)
                    .attr("topic", topic)
                    .log("Invalid topic name");
            throw new RestException(Status.PRECONDITION_FAILED, "Topic name is not valid");
        }
    }

View on GitHub (pinned to 820761864e)

Solutions

1. Check broker logs for the preceding warn-level exception to find the root cause (usually metadata store connectivity).
2. Verify the broker's configuration-store connection settings (zookeeper/metadataStoreUrl) and that the config cluster is healthy.
3. Retry the admin operation once the metadata store is reachable; the 503 is meant to be transient.
4. If persistent, inspect namespace policies for the affected namespace and repair or recreate them.

// Java: probe metadata store health via an innocuous admin read before the real call
admin.namespaces().getPolicies(namespaceName); // throws if config store unreachable
// if this succeeds, global namespace validation should also succeed

try {
    admin.namespaces().getPolicies(ns);
} catch (PulsarAdminException e) {
    if (e.getStatusCode() == 503) {
        // transient metadata-store issue: back off and retry
        Thread.sleep(retryBackoffMs);
        retry();
    }
}

When it happens

Trigger: Any REST admin call on a global namespace (e.g. PUT/GET namespace policies, create topic under a global namespace) while the namespace policies cannot be read from the metadata store, the configuration store connection is down, or a non-WebApplicationException exception escapes policy validation.

Common situations: Configuration-store/ZooKeeper outage or flaky network between broker and metadata store; namespace deleted concurrently while being validated; cluster misconfiguration where the global namespace's cluster list references an unknown cluster causing unexpected exceptions.

Related errors

• Namespace name is not valid
• Tenant name or namespace is not valid
• Namespace does not exist
• Failed to validate global cluster configuration : ns=%s ems
• Metadata store address argument is required (--metadata-stor

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