{"record":{"id":"eea3f2b5bb7e6ef6","repo":"temporalio/temporal","slug":"unable-to-register-system-namespace-w","errorCode":null,"errorMessage":"unable to register system namespace: %w","messagePattern":"unable to register system namespace: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"temporal/server_impl.go","lineNumber":195,"sourceCode":"\t\tMetricsHandler:             metricsHandler,\n\t\tLogger:                     logger,\n\t\tSerializer:                 serializer,\n\t})\n\tdefer factory.Close()\n\n\tmetadataManager, err := factory.NewMetadataManager()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"unable to initialize metadata manager: %w\", err)\n\t}\n\tdefer metadataManager.Close()\n\tctx, cancel := context.WithTimeout(\n\t\theaders.SetCallerInfo(ctx, headers.SystemBackgroundHighCallerInfo),\n\t\t30*time.Second,\n\t)\n\tdefer cancel()\n\n\tif err = metadataManager.InitializeSystemNamespaces(ctx, currentClusterName); err != nil {\n\t\treturn fmt.Errorf(\"unable to register system namespace: %w\", err)\n\t}\n\treturn nil\n}\n","sourceCodeStart":177,"sourceCodeEnd":199,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/server_impl.go#L177-L199","documentation":"Wraps the error from metadataManager.InitializeSystemNamespaces(ctx, currentClusterName), the step that registers the 'temporal-system' namespace for the current cluster. After the metadata manager is created, the server must write/register system namespaces within a 30-second context; a persistence write error, an entity-exists conflict, or a context deadline exceeded produces this error and aborts startup.","triggerScenarios":"temporal.Server.Start(ctx) -> initSystemNamespaces, when InitializeSystemNamespaces fails: the underlying CreateNamespace/UpdateNamespace call errors (storage failure, condition/failure, serialization error), or the 30s timeout context is cancelled before the write completes.","commonSituations":"Slow or overloaded datastore exceeding the 30s deadline; cluster name changed in config causing conflicting namespace rows; partial schema state from a previously failed bootstrap; network interruption mid-write; concurrent first-time startup of multiple server nodes racing to initialize the same system namespace.","solutions":["Read the wrapped cause: EntityAlreadyExists vs timeout vs storage error lead to different fixes","If it's a timeout, check DB latency/load and network between server and datastore; the operation must finish in 30 seconds","If it's an already-exists/conflict error (e.g. after cluster rename or retry), verify the existing temporal-system namespace state and clusterName config consistency","Ensure only one node performs initial bootstrap or that retries are safe for your persistence backend","Re-run schema update if the wrapped error indicates missing/legacy metadata tables"],"exampleFix":"// before: two server replicas start simultaneously on an empty DB and race on namespace creation\n// docker compose scale temporal=2 -> unable to register system namespace: timeout\n\n// after: run bootstrap once, then scale\n// docker compose up -d temporal\n// wait for readiness, then:\n// docker compose up --scale temporal=3 -d","handlingStrategy":"retry","validationCode":"// confirm metadata store is up and empty-state bootstrap is single-flight:\n// if err := db.Ping(); err != nil { return err }\n// coordinate bootstrap (e.g. a lock/leader election) so only one node initializes\n// system namespaces on a fresh database","typeGuard":null,"tryCatchPattern":"err := srv.Start(ctx)\nif err != nil && strings.Contains(err.Error(), \"unable to register system namespace\") {\n\t// transient storage/timeout errors may be retried; EntityAlreadyExists-style\n\t// conflicts need inspection instead\n\tif isTransient(err) { // e.g. deadline exceeded, connection reset\n\t\ttime.Sleep(5 * time.Second)\n\t\terr = srv.Start(ctx)\n\t}\n}\nif err != nil { log.Fatal(err) }","preventionTips":["Serialize first-time bootstrap across replicas (leader election or lock)","Keep the datastore responsive — the init window is only 30 seconds","Avoid renaming clusterName without a planned namespace migration","Verify metadata tables are current after schema upgrades","Monitor DB latency at startup time; delays here fail the whole server"],"tags":["namespace","persistence","timeout","startup"],"backgroundTag":"namespace-registration-failed","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}