{"record":{"id":"0a4ad149f3adcd88","repo":"temporalio/temporal","slug":"error-while-loading-metadata-from-cluster-w","errorCode":null,"errorMessage":"error while loading metadata from cluster: %w","messagePattern":"error while loading metadata from cluster: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"temporal/fx.go","lineNumber":767,"sourceCode":"\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\n\tcurrentClusterName := svc.ClusterMetadata.CurrentClusterName\n\tcurrentClusterInfo := svc.ClusterMetadata.ClusterInformation[currentClusterName]\n\tif uuid.Validate(currentClusterInfo.ClusterID) != nil {\n\t\tif currentClusterInfo.ClusterID != \"\" {\n\t\t\tlogger.Warn(\"Cluster Id in Cluster Metadata config is not a valid uuid. Generating a new Cluster Id\")\n\t\t}","sourceCodeStart":749,"sourceCodeEnd":785,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/fx.go#L749-L785","documentation":"Wraps an error from ClusterMetadataLoader.LoadAndMergeWithStaticConfig, which loads the cluster metadata record from the DB and merges it with the static config (initial cluster name, etc.) during startup.","triggerScenarios":"Server startup; LoadAndMergeWithStaticConfig fails, e.g. persistence update of the merged metadata fails, version conflict with a concurrent node, or invalid merged state.","commonSituations":"Multiple nodes starting simultaneously and racing on the metadata record version; cluster name conflicts between static config and DB record; DB write failures.","solutions":["Check the wrapped root error for the specific merge/persistence failure","Ensure the clusterName in config matches the existing cluster metadata record","Avoid simultaneous first-boot of many nodes; bootstrap once then scale","Verify DB write permissions for the persistence user"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure config cluster name matches existing record\nif rec, err := getClusterMetadata(ctx); err == nil && rec.ClusterName != cfg.ClusterName {\n    return fmt.Errorf(\"cluster name mismatch: cfg=%s db=%s\", cfg.ClusterName, rec.ClusterName)\n}","typeGuard":null,"tryCatchPattern":"if err := startServer(ctx); err != nil && strings.Contains(err.Error(), \"loading metadata from cluster\") {\n    // possible transient conflict between nodes; retry after delay\n    time.Sleep(backoff)\n    return startServer(ctx)\n}","preventionTips":["Bootstrap cluster metadata once, then scale out","Keep static config clusterName stable across upgrades","Avoid concurrent full-cluster cold starts"],"tags":["cluster-metadata","persistence","startup"],"backgroundTag":"cluster-metadata-load-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}