temporalio/temporal · critical

failed to initialize current cluster metadata

Error message

failed to initialize current cluster metadata

What it means

clusterMetadataInitErr is a sentinel error used by the temporal server fx dependency graph to signal that the current-cluster metadata could not be initialized during service boot. It is wrapped with the underlying cause, so the full log line contains the real failure (e.g. persistence or config errors).

Source

Thrown at temporal/fx.go:68

	"go.temporal.io/server/common/searchattribute"
	"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

View on GitHub (pinned to bde624efd1)

Solutions

1. Read the wrapped cause after this message in the server logs (e.g. persistence connection failure) and fix that
2. Validate the clusterMetadata config block: currentClusterName, failoverVersion, clusterInformation (initialFailoverVersion, isEnabled)
3. Ensure the persistence store is reachable and schema (setup-schema/update-schema) has been applied
4. Run temporal server config validation (temporal config validate / tctl dry checks) before deploy

Example fix

// before
currentClusterMetadata: persistenceClient unreachable, clusterMetadataPersistence not set up
# temporal.yaml
persistence:
  defaultStore: "missing"
// after
# apply schema then configure
temporal-sql-tool setup-schema --db temporal
# temporal.yaml
persistence:
  defaultStore: sql
  datastores:
    sql:
      sqlPluginName: "mysql8"
      databaseName: temporal

// validate cluster metadata block before boot
if cfg.ClusterMetadata == nil || cfg.ClusterMetadata.CurrentClusterName == "" {
    return errors.New("clusterMetadata.currentClusterName must be set")
}
if len(cfg.ClusterMetadata.ClusterInformation) == 0 {
    return errors.New("clusterMetadata.clusterInformation must define at least the current cluster")
}

func clusterInfoExists(cfg *config.Config, name string) bool {
    return cfg.ClusterMetadata != nil && cfg.ClusterMetadata.ClusterInformation[name] != nil
}

if err := server.Start(); err != nil {
    if strings.Contains(err.Error(), "failed to initialize current cluster metadata") {
        log.Fatalf("cluster metadata init failed; check DB reachability/schema: %v", err)
    }
    return err
}

When it happens

Trigger: Starting any temporal-server service (frontend/history/etc.) when the current cluster metadata provider fails to construct — typically bad clusterMetadata config (invalid persistence, unreachable DB, malformed clusterInformation).

Common situations: Misconfigured temporal.yaml clusterMetadata section; database down or schema not migrated on first boot; duplicate/invalid cluster name config; fx dependency injection failure at startup.

Related errors

• missing current cluster metadata under clusterMetadata.Clust
• unable to create metrics handler: %w
• 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/c91eb46100f074d1. Report an issue: GitHub.