{"record":{"id":"b5a639ec5dc01d40","repo":"temporalio/temporal","slug":"error-initializing-cluster-metadata-manager-w","errorCode":null,"errorMessage":"error initializing cluster metadata manager: %w","messagePattern":"error initializing cluster metadata manager: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"temporal/fx.go","lineNumber":682,"sourceCode":"\t\tmetricsHandler,\n\t\ttelemetry.NoopTracerProvider,\n\t\tserializer,\n\t)\n\tfactory := persistenceFactoryProvider(persistenceClient.NewFactoryParams{\n\t\tDataStoreFactory:           dataStoreFactory,\n\t\tCfg:                        &svc.Persistence,\n\t\tPersistenceMaxQPS:          nil,\n\t\tPersistenceNamespaceMaxQPS: nil,\n\t\tClusterName:                persistenceClient.ClusterName(svc.ClusterMetadata.CurrentClusterName),\n\t\tMetricsHandler:             metricsHandler,\n\t\tLogger:                     logger,\n\t\tSerializer:                 serializer,\n\t})\n\tdefer factory.Close()\n\n\tclusterMetadataManager, err := factory.NewClusterMetadataManager()\n\tif err != nil {\n\t\treturn svc.ClusterMetadata, svc.Persistence, fmt.Errorf(\"error initializing cluster metadata manager: %w\", err)\n\t}\n\tdefer clusterMetadataManager.Close()\n\n\tvisCSAOverride := map[enumspb.IndexedValueType]int{}\n\tfor tpName, value := range svc.Visibility.PersistenceCustomSearchAttributes {\n\t\tsaType, ok := enumspb.IndexedValueType_shorthandValue[tpName]\n\t\tif !ok {\n\t\t\treturn svc.ClusterMetadata,\n\t\t\t\tsvc.Persistence,\n\t\t\t\tfmt.Errorf(\"invalid search attribute type: %s\", tpName)\n\t\t}\n\t\tif value < 0 || value > 99 {\n\t\t\treturn svc.ClusterMetadata,\n\t\t\t\tsvc.Persistence,\n\t\t\t\tfmt.Errorf(\n\t\t\t\t\t\"invalid number of custom search attributes for type %s (must be between 0 and 99)\",\n\t\t\t\t\ttpName,\n\t\t\t\t)","sourceCodeStart":664,"sourceCodeEnd":700,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/fx.go#L664-L700","documentation":"Wraps an error from factory.NewClusterMetadataManager() during persistence bootstrap (cluster metadata provider in the FX graph). The cluster metadata manager is the persistence-layer accessor for cluster metadata records; failure here means the persistence factory could not build that manager (bad driver config, connection failure, or unsupported store).","triggerScenarios":"Starting the server when the persistence datastore backing cluster metadata cannot construct a ClusterMetadataManager — e.g. unreachable Cassandra/SQL database, unsupported persistence type, or driver init error.","commonSituations":"Database down or wrong host/port in persistence config; unsupported store driver for cluster metadata; bad credentials preventing the driver from initializing schema access.","solutions":["Read the wrapped root error for the driver-specific cause","Verify the clusterMetadata persistence datastore is reachable and credentials are correct","Confirm the persistence type (cassandra/postgres/mysql/sqlite) is supported and schema is applied","Run temporal-sql-tool / temporal-cassandra-tool to validate schema connectivity"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-check connectivity before starting the server\nif err := pingDatastore(cfg.Persistence.DataStores[store]); err != nil {\n    return err\n}","typeGuard":null,"tryCatchPattern":"if err := startServer(opts); err != nil {\n    // root cause is wrapped; inspect with errors.As/Unwrap\n    return fmt.Errorf(\"cluster metadata manager init: %w\", err)\n}","preventionTips":["Health-check the database before launching Temporal","Verify driver credentials and supported store types in config review","Apply schema with temporal tools before first boot"],"tags":["persistence","cluster-metadata","startup","database"],"backgroundTag":"persistence-init-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}