{"record":{"id":"192a38019e6f623c","repo":"temporalio/temporal","slug":"master-cluster-name-is-empty","errorCode":null,"errorMessage":"Master cluster name is empty","messagePattern":"Master cluster name is empty","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"common/cluster/metadata.go","lineNumber":148,"sourceCode":"\t\tclusterCallbackLock   sync.RWMutex\n\t\tclusterChangeCallback map[any]CallbackFn\n\t}\n)\n\nfunc NewMetadata(\n\tenableGlobalNamespace bool,\n\tfailoverVersionIncrement int64,\n\tmasterClusterName string,\n\tcurrentClusterName string,\n\tclusterInfo map[string]ClusterInformation,\n\tclusterMetadataStore persistence.ClusterMetadataManager,\n\trefreshDuration dynamicconfig.DurationPropertyFn,\n\tlogger log.Logger,\n) Metadata {\n\tif len(clusterInfo) == 0 {\n\t\tpanic(\"Empty cluster information\")\n\t} else if len(masterClusterName) == 0 {\n\t\tpanic(\"Master cluster name is empty\")\n\t} else if len(currentClusterName) == 0 {\n\t\tpanic(\"Current cluster name is empty\")\n\t} else if failoverVersionIncrement == 0 || failoverVersionIncrement > math.MaxInt32 {\n\t\tpanic(\"Version increment <= 0 or > 2147483647\")\n\t}\n\n\tversionToClusterName, err := updateVersionToClusterName(clusterInfo, failoverVersionIncrement)\n\tif err != nil {\n\t\t// nolint:forbidigo // matches the other startup-config panics in this constructor\n\t\tpanic(err.Error())\n\t}\n\tif _, ok := clusterInfo[currentClusterName]; !ok {\n\t\tpanic(\"Current cluster is not specified in cluster info\")\n\t}\n\tif _, ok := clusterInfo[masterClusterName]; !ok {\n\t\tpanic(\"Master cluster is not specified in cluster info\")\n\t}\n","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/common/cluster/metadata.go#L130-L166","documentation":"NewMetadata in common/cluster/metadata.go also panics when masterClusterName is an empty string. In multi-cluster replication the master cluster name identifies the cluster that owns global domain failover versioning; without it, replication semantics are undefined, so the constructor refuses to proceed.","triggerScenarios":"Calling NewMetadata with masterClusterName == \"\" — e.g. `masterClusterName` unset in config, or an empty `masterClusterName` key in the clusters section while global domains/replication are enabled.","commonSituations":"Single-cluster deployments where the operator omitted master cluster settings but later enabled cross-cluster replication; config upgrades/drift dropping the masterClusterName field; env-specific config layers overriding masterClusterName with an empty string.","solutions":["Set the master cluster name in config (clusterMetadata.masterClusterName) to a cluster defined in clusterInfo","Ensure the named master cluster also appears in the clusterInfo map (otherwise validation fails later)","Add a config lint/pre-start check that masterClusterName is non-empty when replication is enabled","Review env config overrides so they don't blank the master cluster name"],"exampleFix":"// before (config.yaml)\nclusterMetadata:\n  enableGlobalDomain: true\n  # masterClusterName missing\n// after (config.yaml)\nclusterMetadata:\n  enableGlobalDomain: true\n  masterClusterName: \"active\"\n  clusters:\n    - clusterName: \"active\"\n","handlingStrategy":"validation","validationCode":"if masterClusterName == \"\" {\n    return errors.New(\"config error: masterClusterName must be set when cluster metadata is used\")\n}\nif _, ok := clusterInfo[masterClusterName]; !ok {\n    return fmt.Errorf(\"master cluster %q not present in clusterInformation\", masterClusterName)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set masterClusterName in the clusterMetadata config block","Ensure the master cluster is also listed in clusterInformation","Add a pre-start config check tying masterClusterName to the cluster map","Audit env config overlays for fields that resolve to empty strings"],"tags":["cluster","config","panic","startup","replication"],"backgroundTag":"empty-cluster-config","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}