temporalio/temporal · critical

missing current cluster metadata under clusterMetadata.Clust

Error message

missing current cluster metadata under clusterMetadata.ClusterInformation

What it means

missingCurrentClusterMetadataErr is returned when the server configuration does not define the current cluster under clusterMetadata.ClusterInformation. The server requires an entry describing the current cluster (persistence settings, failover version, enabled flag) to initialize cross-cluster metadata.

Source

Thrown at temporal/fx.go:69

	"go.temporal.io/server/common/searchattribute/sadefs"
	"go.temporal.io/server/common/telemetry"
	"go.temporal.io/server/common/testing/testhooks"
	"go.temporal.io/server/common/wideevents"
	"go.temporal.io/server/service/frontend"
	"go.temporal.io/server/service/history"
	"go.temporal.io/server/service/history/replication"
	"go.temporal.io/server/service/history/tasks"
	"go.temporal.io/server/service/matching"
	"go.temporal.io/server/service/worker"
	"go.uber.org/fx"
	"go.uber.org/fx/fxevent"
	expmaps "golang.org/x/exp/maps"
	"google.golang.org/grpc"
)

var (
	clusterMetadataInitErr           = errors.New("failed to initialize current cluster metadata")
	missingCurrentClusterMetadataErr = errors.New("missing current cluster metadata under clusterMetadata.ClusterInformation")
	missingServiceInStaticHosts      = errors.New("hosts are missing in static hosts for service: ")
)

type (
	ServicesGroupOut struct {
		fx.Out
		Services *ServicesMetadata `group:"services"`
	}

	ServicesGroupIn struct {
		fx.In
		Services []*ServicesMetadata `group:"services"`
	}

	ServicesMetadata struct {
		app         *fx.App
		serviceName primitives.ServiceName
		logger      log.Logger

View on GitHub (pinned to bde624efd1)

Solutions

1. Add a clusterInformation entry whose key equals clusterMetadata.currentClusterName
2. Set initialFailoverVersion (0 for single-cluster) and isEnabled: true for the current cluster entry
3. Start from the shipped config template in config/config_template.yaml and fill in all clusterMetadata fields
4. Diff your effective config against the expected one (enable config loading logs) to spot the dropped key

Example fix

// before
clusterMetadata:
  enableGlobalNamespace: false
  currentClusterName: "active"
  clusterInformation: {}
// after
clusterMetadata:
  enableGlobalNamespace: false
  currentClusterName: "active"
  clusterInformation:
    active:
      enabled: true
      initialFailoverVersion: 0
      clusterAddress: "127.0.0.1:7233"

func validateCurrentCluster(cfg *config.Config) error {
    cm := cfg.ClusterMetadata
    if cm == nil || cm.CurrentClusterName == "" { return errors.New("currentClusterName missing") }
    info, ok := cm.ClusterInformation[cm.CurrentClusterName]
    if !ok { return fmt.Errorf("clusterInformation missing entry for %q", cm.CurrentClusterName) }
    if !info.IsEnabled { return errors.New("current cluster must be enabled") }
    return nil
}

func hasCurrentClusterEntry(cfg *config.Config) bool {
    return cfg.ClusterMetadata != nil && cfg.ClusterMetadata.ClusterInformation[cfg.ClusterMetadata.CurrentClusterName] != nil
}

if err := server.Start(); err != nil {
    if strings.Contains(err.Error(), "missing current cluster metadata") {
        log.Fatalf("config error: add clusterInformation entry for the current cluster")
    }
    return err
}

When it happens

Trigger: Booting temporal server with clusterMetadata.currentClusterName set to a name that has no matching key in clusterMetadata.ClusterInformation, or with ClusterInformation empty entirely.

Common situations: Renaming currentClusterName without updating clusterInformation; template config left unfilled; multi-cluster config merge dropping the current cluster's entry; typo in the cluster information map key.

Related errors

• failed to initialize current cluster metadata
• unable to load config: %w
• hosts are missing in static hosts for service: ${service}
• global.authorization.remoteClusterAuth.require is true but n
• env, config, zone can not be set if configFilePath is set

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