temporalio/temporal · error

current cluster %q is missing from cluster metadata

Error message

current cluster %q is missing from cluster metadata

What it means

SyncWorkflowStateFromSource resolves the current cluster's metadata before pulling workflow state from the active cluster. If the current cluster's name cannot be found in the cluster metadata map, the cluster is misconfigured. It returns SyncWorkflowStateResultSkipped along with this error so the caller's verification flow still records the failure.

Source

Thrown at service/history/api/workflowresend/sync_workflow_state.go:60

	currentClusterName := clusterMetadata.GetCurrentClusterName()
	namespaceRegistry := shardContext.GetNamespaceRegistry()
	namespaceEntry, err := namespaceRegistry.GetNamespaceByID(namespaceID)
	if err != nil {
		return SyncWorkflowStateResultSkipped, err
	}
	if !namespaceEntry.IsOnCluster(currentClusterName) {
		return SyncWorkflowStateResultSkipped, nil
	}

	routingKey := namespace.RoutingKey{ID: execution.GetWorkflowId()}
	activeClusterName := namespaceEntry.ActiveClusterName(routingKey)
	if activeClusterName == currentClusterName {
		return SyncWorkflowStateResultSkipped, nil
	}

	targetClusterInfo, ok := clusterMetadata.GetAllClusterInfo()[currentClusterName]
	if !ok {
		return SyncWorkflowStateResultSkipped, fmt.Errorf("current cluster %q is missing from cluster metadata", currentClusterName)
	}
	remoteAdminClient, err := shardContext.GetRemoteAdminClient(activeClusterName)
	if err != nil {
		return SyncWorkflowStateResultSkipped, err
	}
	if onSourceResolved != nil {
		onSourceResolved(activeClusterName)
	}

	resp, err := remoteAdminClient.SyncWorkflowState(ctx, &adminservice.SyncWorkflowStateRequest{
		NamespaceId:         namespaceID.String(),
		Execution:           execution,
		ArchetypeId:         chasm.WorkflowArchetypeID,
		VersionedTransition: versionedTransition,
		VersionHistories:    versionHistories,
		TargetClusterId:     int32(targetClusterInfo.InitialFailoverVersion),
	})
	if err != nil {

View on GitHub (pinned to bde624efd1)

Solutions

  1. Verify the cluster's currentClusterName (config + clusterMetadata) matches an entry registered via cluster metadata initialization / UpdateClusterInfo
  2. Check the metadata persistence backend (e.g. the clusters table in the visibility DB) contains the current cluster's name and the config points at the right DB
  3. If this is a standby cluster being registered, ensure the cluster is added to all peers' cluster metadata before running workflow resends

Example fix

// before
// clusterName in config: "clusterA" but metadata only has "cluster-a"
// after
// align config currentClusterName with the registered metadata entry
// or register it:
// err := metadataInitializer.UpdateClusterInfo(name, clusterInfo)
Defensive patterns

Strategy: validation

Validate before calling

info, ok := clusterMetadata.GetAllClusterInfo()[currentClusterName]
if !ok {
	return fmt.Errorf("cluster %q not registered in metadata", currentClusterName)
}

Try / catch

result, err := syncWorkflowStateFromSource(ctx)
if err != nil && strings.Contains(err.Error(), "missing from cluster metadata") {
	// abort operation; fix cluster registration before retrying
}

Prevention

When it happens

Trigger: SyncWorkflowStateFromSource is called (from resendParentAndVerify, resendChildAndVerify, or sync CLI) on a cluster whose currentClusterName, obtained from clusterMetadata, is absent from the map returned by clusterMetadata.GetAllClusterInfo().

Common situations: Cluster name changed in config but metadata persistence was not updated; new cluster added without registering it in the cluster metadata table; replication/metadata store lag or corruption after failover; typo in currentClusterName configuration.

Related errors

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