What causes "Current cluster name is empty" in temporalio/temporal?

Set the current cluster name explicitly, e.g. cluster.NewMetadata(clusterInfo, "active", "active", failoverVersionIncrement, nil)

temporalio/temporal · critical

Current cluster name is empty

Error message

Current cluster name is empty

What it means

NewMetadata validates its configuration at construction time and panics if currentClusterName is empty. The metadata API requires a non-empty current cluster name because it is used to look up cluster info, compute cluster IDs, and decide replication behavior. This is a fail-fast startup invariant, not a runtime error.

Source

Thrown at common/cluster/metadata.go:150

	}
)

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")
	}

	copyClusterInfo := make(map[string]ClusterInformation)
	maps.Copy(copyClusterInfo, clusterInfo)

View on GitHub (pinned to bde624efd1)

Solutions

Set the current cluster name explicitly, e.g. cluster.NewMetadata(clusterInfo, "active", "active", failoverVersionIncrement, nil)
Check the temporal config template/binding so currentClusterName resolves to a non-empty value before constructing metadata
Call NewMetadataForTest in tests, which supplies a valid default current cluster name

Example fix

// before
md := cluster.NewMetadata(clusterInfo, "master", "", failoverVersionIncrement, nil, nil)
// after
md := cluster.NewMetadata(clusterInfo, "master", "current-cluster-name", failoverVersionIncrement, nil, nil)

Defensive patterns

Strategy: validation

Validate before calling

if currentClusterName == "" {
  return fmt.Errorf("currentClusterName must be non-empty before constructing cluster metadata")
}

Prevention

Validate all cluster config fields (names, increment) before calling NewMetadata
Use config templates with required-field checks so empty cluster names fail at config load
In tests, use NewMetadataForTest to get valid defaults

When it happens

Trigger: Calling cluster.NewMetadata(clusterInfo, masterClusterName, "", failoverVersionIncrement, ...) or NewMetadataFromConfig with a config file where the currentClusterName field is set to "" or missing.

Common situations: Empty or mis-rendered temporal cluster config (e.g. config template env var for cluster name not set), copying a multi-cluster config template and deleting the current-cluster entry, or a test harness passing an empty string literal.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

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