temporalio/temporal · critical

Master cluster name is empty

Error message

Master cluster name is empty

What it means

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.

Source

Thrown at common/cluster/metadata.go:148

		clusterCallbackLock   sync.RWMutex
		clusterChangeCallback map[any]CallbackFn
	}
)

func NewMetadata(
	enableGlobalNamespace bool,
	failoverVersionIncrement int64,
	masterClusterName string,
	currentClusterName string,
	clusterInfo map[string]ClusterInformation,
	clusterMetadataStore persistence.ClusterMetadataManager,
	refreshDuration dynamicconfig.DurationPropertyFn,
	logger log.Logger,
) Metadata {
	if len(clusterInfo) == 0 {
		panic("Empty cluster information")
	} else if len(masterClusterName) == 0 {
		panic("Master cluster name is empty")
	} else if len(currentClusterName) == 0 {
		panic("Current cluster name is empty")
	} else if failoverVersionIncrement == 0 || failoverVersionIncrement > math.MaxInt32 {
		panic("Version increment <= 0 or > 2147483647")
	}

	versionToClusterName, err := updateVersionToClusterName(clusterInfo, failoverVersionIncrement)
	if err != nil {
		// nolint:forbidigo // matches the other startup-config panics in this constructor
		panic(err.Error())
	}
	if _, ok := clusterInfo[currentClusterName]; !ok {
		panic("Current cluster is not specified in cluster info")
	}
	if _, ok := clusterInfo[masterClusterName]; !ok {
		panic("Master cluster is not specified in cluster info")
	}

View on GitHub (pinned to bde624efd1)

Solutions

1. Set the master cluster name in config (clusterMetadata.masterClusterName) to a cluster defined in clusterInfo
2. Ensure the named master cluster also appears in the clusterInfo map (otherwise validation fails later)
3. Add a config lint/pre-start check that masterClusterName is non-empty when replication is enabled
4. Review env config overrides so they don't blank the master cluster name

Example fix

// before (config.yaml)
clusterMetadata:
  enableGlobalDomain: true
  # masterClusterName missing
// after (config.yaml)
clusterMetadata:
  enableGlobalDomain: true
  masterClusterName: "active"
  clusters:
    - clusterName: "active"

if masterClusterName == "" {
    return errors.New("config error: masterClusterName must be set when cluster metadata is used")
}
if _, ok := clusterInfo[masterClusterName]; !ok {
    return fmt.Errorf("master cluster %q not present in clusterInformation", masterClusterName)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Empty cluster information
• <dynamic archival cluster state err>
• Unexpected frontend service name
• missing current cluster metadata under clusterMetadata.Clust
• failed to get config files: %w

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/192a38019e6f623c. Report an issue: GitHub.