{"record":{"id":"fa8494e03659f9ce","repo":"apache/pulsar","slug":"failed-to-validate-global-cluster-configuration","errorCode":null,"errorMessage":"Failed to validate global cluster configuration","messagePattern":"Failed to validate global cluster configuration","errorType":"http","errorClass":"org.apache.pulsar.broker.admin.RestException","httpStatus":503,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java","lineNumber":232,"sourceCode":"                    .attr(\"namespace\", namespace)\n                    .log(\"Invalid namespace name\");\n            throw new RestException(Status.PRECONDITION_FAILED, \"Namespace name is not valid\");\n        }\n    }\n\n    protected void validateGlobalNamespaceOwnership() {\n        try {\n            validateGlobalNamespaceOwnership(this.namespaceName);\n        } catch (IllegalArgumentException e) {\n            throw new RestException(Status.PRECONDITION_FAILED, \"Tenant name or namespace is not valid\");\n        } catch (RestException re) {\n            throw re;\n        } catch (Exception e) {\n            log.warn()\n                    .attr(\"namespace\", namespaceName)\n                    .exceptionMessage(e)\n                    .log(\"Failed to validate global cluster configuration\");\n            throw new RestException(Status.SERVICE_UNAVAILABLE, \"Failed to validate global cluster configuration\");\n        }\n    }\n    protected void validateTopicName(String tenant, String namespace, String encodedTopic) {\n        String topic = Codec.decode(encodedTopic);\n        try {\n            this.namespaceName = NamespaceName.get(tenant, namespace);\n            this.topicName = TopicName.get(domain(), namespaceName, topic);\n        } catch (IllegalArgumentException e) {\n            log.warn()\n                    .attr(\"domain\", domain())\n                    .attr(\"tenant\", tenant)\n                    .attr(\"namespace\", namespace)\n                    .attr(\"topic\", topic)\n                    .log(\"Invalid topic name\");\n            throw new RestException(Status.PRECONDITION_FAILED, \"Topic name is not valid\");\n        }\n    }\n","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/AdminResource.java#L214-L250","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check broker logs for the preceding warn-level exception to find the root cause (usually metadata store connectivity).","Verify the broker's configuration-store connection settings (zookeeper/metadataStoreUrl) and that the config cluster is healthy.","Retry the admin operation once the metadata store is reachable; the 503 is meant to be transient.","If persistent, inspect namespace policies for the affected namespace and repair or recreate them."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Java: probe metadata store health via an innocuous admin read before the real call\nadmin.namespaces().getPolicies(namespaceName); // throws if config store unreachable\n// if this succeeds, global namespace validation should also succeed","typeGuard":null,"tryCatchPattern":"try {\n    admin.namespaces().getPolicies(ns);\n} catch (PulsarAdminException e) {\n    if (e.getStatusCode() == 503) {\n        // transient metadata-store issue: back off and retry\n        Thread.sleep(retryBackoffMs);\n        retry();\n    }\n}","preventionTips":["Monitor broker-to-metadata-store connectivity and alert before admin operations fail.","Add retry with exponential backoff around admin calls that can return 503.","Keep configuration-store settings consistent across brokers in the cluster.","Check broker logs for the underlying warn exception before reconfiguring anything."],"tags":["http-503","metadata-store","admin-api","namespace"],"backgroundTag":"metadata-store-unavailable","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"}