temporalio/temporal · error

error while updating cluster metadata: %w

Error message

error while updating cluster metadata: %w

What it means

Error updating cluster metadata (e.g. persisting cluster name / initial cluster registration) during temporal server bootstrap via fx; the wrapped error comes from the cluster metadata manager.

Source

Thrown at temporal/fx.go:866

		updateDBRecord = true
	}

	if updateIndexSearchAttributes(initialIndexSearchAttributes, currentClusterDBRecord) {
		updateDBRecord = true
	}

	if !updateDBRecord {
		return nil
	}

	applied, err := clusterMetadataManager.SaveClusterMetadata(
		ctx,
		&persistence.SaveClusterMetadataRequest{
			ClusterMetadata: currentClusterDBRecord.ClusterMetadata,
			Version:         currentClusterDBRecord.Version,
		})
	if !applied || err != nil {
		return fmt.Errorf("error while updating cluster metadata: %w", err)
	}
	return nil
}

func overwriteCurrentClusterMetadataWithDBRecord(
	svc *config.Config,
	currentClusterDBRecord *persistence.GetClusterMetadataResponse,
	logger log.Logger,
) {
	clusterMetadata := svc.ClusterMetadata
	if currentClusterDBRecord.IsGlobalNamespaceEnabled && !clusterMetadata.EnableGlobalNamespace {
		logger.Warn(
			mismatchLogMessage,
			tag.Key("clusterMetadata.EnableGlobalNamespace"),
			tag.IgnoredValue(clusterMetadata.EnableGlobalNamespace),
			tag.Value(currentClusterDBRecord.IsGlobalNamespaceEnabled))
		svc.ClusterMetadata.EnableGlobalNamespace = currentClusterDBRecord.IsGlobalNamespaceEnabled
	}

View on GitHub (pinned to bde624efd1)

Solutions

1. Retry the operation; a concurrent writer likely won (applied=false)
2. Check the wrapped error for DB-level failures
3. Serialize cluster metadata bootstrap (single node / leader) for initial cluster setup

err := startServer(ctx)
if err != nil && strings.Contains(err.Error(), "error while updating cluster metadata") {
    // optimistic concurrency: another node won; retry with fresh version
    return retry.Do(func() error { return startServer(ctx) },
        retry.Attempts(3), retry.Delay(backoff))
}

When it happens

Trigger: initCurrentClusterMetadataRecord calls SaveClusterMetadata with the current record and version; applied == false (optimistic concurrency conflict — another writer changed the record) or err != nil.

Common situations: Two history nodes racing to update cluster metadata during rolling restart; the metadata version advanced concurrently; DB write failure or timeout.

Related errors

• %w. provided table version: %v current table version: %v
• rowsAffected returned %v shards instead of one
• error initializing cluster metadata manager: %w
• error while fetching cluster metadata: %w
• error while loading metadata from cluster: %w

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