{"record":{"id":"c91eb46100f074d1","repo":"temporalio/temporal","slug":"failed-to-initialize-current-cluster-metadata","errorCode":null,"errorMessage":"failed to initialize current cluster metadata","messagePattern":"failed to initialize current cluster metadata","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"temporal/fx.go","lineNumber":68,"sourceCode":"\t\"go.temporal.io/server/common/searchattribute\"\n\t\"go.temporal.io/server/common/searchattribute/sadefs\"\n\t\"go.temporal.io/server/common/telemetry\"\n\t\"go.temporal.io/server/common/testing/testhooks\"\n\t\"go.temporal.io/server/common/wideevents\"\n\t\"go.temporal.io/server/service/frontend\"\n\t\"go.temporal.io/server/service/history\"\n\t\"go.temporal.io/server/service/history/replication\"\n\t\"go.temporal.io/server/service/history/tasks\"\n\t\"go.temporal.io/server/service/matching\"\n\t\"go.temporal.io/server/service/worker\"\n\t\"go.uber.org/fx\"\n\t\"go.uber.org/fx/fxevent\"\n\texpmaps \"golang.org/x/exp/maps\"\n\t\"google.golang.org/grpc\"\n)\n\nvar (\n\tclusterMetadataInitErr           = errors.New(\"failed to initialize current cluster metadata\")\n\tmissingCurrentClusterMetadataErr = errors.New(\"missing current cluster metadata under clusterMetadata.ClusterInformation\")\n\tmissingServiceInStaticHosts      = errors.New(\"hosts are missing in static hosts for service: \")\n)\n\ntype (\n\tServicesGroupOut struct {\n\t\tfx.Out\n\t\tServices *ServicesMetadata `group:\"services\"`\n\t}\n\n\tServicesGroupIn struct {\n\t\tfx.In\n\t\tServices []*ServicesMetadata `group:\"services\"`\n\t}\n\n\tServicesMetadata struct {\n\t\tapp         *fx.App\n\t\tserviceName primitives.ServiceName","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/fx.go#L50-L86","documentation":"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).","triggerScenarios":"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).","commonSituations":"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.","solutions":["Read the wrapped cause after this message in the server logs (e.g. persistence connection failure) and fix that","Validate the clusterMetadata config block: currentClusterName, failoverVersion, clusterInformation (initialFailoverVersion, isEnabled)","Ensure the persistence store is reachable and schema (setup-schema/update-schema) has been applied","Run temporal server config validation (temporal config validate / tctl dry checks) before deploy"],"exampleFix":"// before\ncurrentClusterMetadata: persistenceClient unreachable, clusterMetadataPersistence not set up\n# temporal.yaml\npersistence:\n  defaultStore: \"missing\"\n// after\n# apply schema then configure\ntemporal-sql-tool setup-schema --db temporal\n# temporal.yaml\npersistence:\n  defaultStore: sql\n  datastores:\n    sql:\n      sqlPluginName: \"mysql8\"\n      databaseName: temporal","handlingStrategy":"validation","validationCode":"// validate cluster metadata block before boot\nif cfg.ClusterMetadata == nil || cfg.ClusterMetadata.CurrentClusterName == \"\" {\n    return errors.New(\"clusterMetadata.currentClusterName must be set\")\n}\nif len(cfg.ClusterMetadata.ClusterInformation) == 0 {\n    return errors.New(\"clusterMetadata.clusterInformation must define at least the current cluster\")\n}","typeGuard":"func clusterInfoExists(cfg *config.Config, name string) bool {\n    return cfg.ClusterMetadata != nil && cfg.ClusterMetadata.ClusterInformation[name] != nil\n}","tryCatchPattern":"if err := server.Start(); err != nil {\n    if strings.Contains(err.Error(), \"failed to initialize current cluster metadata\") {\n        log.Fatalf(\"cluster metadata init failed; check DB reachability/schema: %v\", err)\n    }\n    return err\n}","preventionTips":["Apply DB schema (setup/update-schema) before first boot","Validate persistence and clusterMetadata config in CI before deploy","Check connectivity to the persistence datastore from the service host"],"tags":["temporal-server","startup","cluster-metadata","fx"],"backgroundTag":"cluster-metadata-init-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}