Unknown cluster name: %v with given cluster initial failover

Error message

Unknown cluster name: %v with given cluster initial failover version map: %v.

What it means

metadataImpl.GetClusterID returns the InitialFailoverVersion of the current cluster. If m.currentClusterName is no longer a key in m.clusterInfo (the map can be mutated by cluster refresh/failover logic), it panics with the current cluster name and the full cluster info map. In a correctly constructed metadata this is unreachable; it guards against internal state drift.

Source

Thrown at common/cluster/metadata.go:279

		},
	}
}

func (m *metadataImpl) IsGlobalNamespaceEnabled() bool {
	return m.enableGlobalNamespace
}

func (m *metadataImpl) IsMasterCluster() bool {
	return m.masterClusterName == m.currentClusterName
}

func (m *metadataImpl) GetClusterID() int64 {
	m.clusterLock.RLock()
	defer m.clusterLock.RUnlock()

	info, ok := m.clusterInfo[m.currentClusterName]
	if !ok {
		panic(fmt.Sprintf(
			"Unknown cluster name: %v with given cluster initial failover version map: %v.",
			m.currentClusterName,
			m.clusterInfo,
		))
	}
	return info.InitialFailoverVersion
}

func (m *metadataImpl) GetNextFailoverVersion(clusterName string, currentFailoverVersion int64) int64 {
	m.clusterLock.RLock()
	defer m.clusterLock.RUnlock()

	info, ok := m.clusterInfo[clusterName]
	if !ok {
		panic(fmt.Sprintf(
			"Unknown cluster name: %v with given cluster initial failover version map: %v.",
			clusterName,
			m.clusterInfo,

View on GitHub (pinned to bde624efd1)

Solutions

Ensure the cluster membership refresh source always includes the local cluster
Recover from the panic at the caller, log the reported cluster info map, and reinitialize metadata from config
Check for races on currentClusterName (it is guarded by clusterLock; do not mutate it externally)

Example fix

// before
cid := metadata.GetClusterID()
// after
func safeClusterID(m cluster.Metadata) (id int64, err error) {
  defer func() { if r := recover(); r != nil { err = fmt.Errorf("getClusterID panic: %v", r) } }()
  return m.GetClusterID(), nil
}

Defensive patterns

Strategy: try-catch

Try / catch

func safeGetClusterID(m cluster.Metadata) (id int64, err error) {
  defer func() {
    if r := recover(); r != nil {
      err = fmt.Errorf("GetClusterID panicked: %v", r)
    }
  }()
  return m.GetClusterID(), nil
}

Prevention

Never mutate metadataImpl internals directly; use the provided APIs
Guarantee cluster membership refresh always includes the local cluster
Monitor refresh failures so a partially updated cluster map is retried, not abandoned

When it happens

Trigger: Calling GetClusterID after the cluster info map was refreshed or mutated such that the current cluster entry was removed or the current cluster name changed without a matching map update.

Common situations: Cluster metadata refresh pulling a new cluster list that excludes the local cluster; custom/test code swapping currentClusterName on a metadataImpl instance.

Related errors

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