{"record":{"id":"6139e420499f7800","repo":"temporalio/temporal","slug":"error-while-fetching-cluster-metadata-w","errorCode":null,"errorMessage":"error while fetching cluster metadata: %w","messagePattern":"error while fetching cluster metadata: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"temporal/fx.go","lineNumber":761,"sourceCode":"\t\t// Ignore invalid cluster metadata\n\t\toverwriteCurrentClusterMetadataWithDBRecord(\n\t\t\tsvc,\n\t\t\tresp,\n\t\t\tlogger,\n\t\t)\n\tcase *serviceerror.NotFound:\n\t\t// Initialize current cluster record\n\t\tif initErr := initCurrentClusterMetadataRecord(\n\t\t\tctx,\n\t\t\tclusterMetadataManager,\n\t\t\tsvc,\n\t\t\tindexSearchAttributes,\n\t\t\tlogger,\n\t\t); initErr != nil {\n\t\t\treturn svc.ClusterMetadata, svc.Persistence, initErr\n\t\t}\n\tdefault:\n\t\treturn svc.ClusterMetadata, svc.Persistence, fmt.Errorf(\"error while fetching cluster metadata: %w\", err)\n\t}\n\n\tclusterLoader := NewClusterMetadataLoader(clusterMetadataManager, logger)\n\terr = clusterLoader.LoadAndMergeWithStaticConfig(ctx, svc)\n\tif err != nil {\n\t\treturn svc.ClusterMetadata, svc.Persistence, fmt.Errorf(\"error while loading metadata from cluster: %w\", err)\n\t}\n\treturn svc.ClusterMetadata, svc.Persistence, nil\n}\n\nfunc initCurrentClusterMetadataRecord(\n\tctx context.Context,\n\tclusterMetadataManager persistence.ClusterMetadataManager,\n\tsvc *config.Config,\n\tinitialIndexSearchAttributes map[string]*persistencespb.IndexSearchAttributes,\n\tlogger log.Logger,\n) error {\n\tvar clusterId string","sourceCodeStart":743,"sourceCodeEnd":779,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/fx.go#L743-L779","documentation":"Wraps the persistence error returned when fetching the current cluster metadata record fails in the default branch of the cluster metadata initialization switch. A persistence read (GetClusterMetadata) failed while bootstrapping cluster metadata, excluding the record-not-found case (handled by init branches).","triggerScenarios":"Server startup calls the cluster metadata provider; GetClusterMetadata returns a non-not-found error — DB connectivity loss, timeout, or internal persistence failure.","commonSituations":"Cassandra/Postgres/MySQL outage or network partition during startup; schema mismatch causing driver errors; persistence layer timeouts under load.","solutions":["Inspect the wrapped root error for the driver-specific cause","Check database availability and network reachability from the server hosts","Verify schema versions match using temporal-cassandra-tool / sql-tool validate","Retry startup after restoring DB connectivity"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// pre-start DB health check\nif err := db.PingContext(ctx); err != nil {\n    return fmt.Errorf(\"metadata DB unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"err := startServer(ctx)\nif err != nil && strings.Contains(err.Error(), \"error while fetching cluster metadata\") {\n    return retry.Do(func() error { return startServer(ctx) }, retry.Attempts(3))\n}","preventionTips":["Monitor DB availability before rolling restarts","Keep persistence timeouts generous enough for startup reads","Validate schema versions to avoid driver-level read errors"],"tags":["persistence","cluster-metadata","database","startup"],"backgroundTag":"cluster-metadata-read-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}