{"record":{"id":"14759f13844b92d6","repo":"temporalio/temporal","slug":"unable-to-initialize-system-namespace-w","errorCode":null,"errorMessage":"unable to initialize system namespace: %w","messagePattern":"unable to initialize system namespace: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"temporal/server_impl.go","lineNumber":103,"sourceCode":"\treturn s\n}\n\nfunc (s *ServerImpl) Start(ctx context.Context) error {\n\ts.logger.Info(\"Starting server for services\", tag.Value(s.so.serviceNames))\n\ts.logger.Debug(s.so.config.String())\n\n\tif err := initSystemNamespaces(\n\t\tctx,\n\t\t&s.persistenceConfig,\n\t\ts.clusterMetadata.CurrentClusterName,\n\t\ts.so.persistenceServiceResolver,\n\t\ts.persistenceFactoryProvider,\n\t\ts.logger,\n\t\ts.so.customDataStoreFactory,\n\t\ts.metricsHandler,\n\t\ts.serializer,\n\t); err != nil {\n\t\treturn fmt.Errorf(\"unable to initialize system namespace: %w\", err)\n\t}\n\n\treturn s.startServices()\n}\n\nfunc (s *ServerImpl) Stop(ctx context.Context) error {\n\tclose(s.stoppedCh)\n\n\tsvcs := slices.Clone(s.servicesMetadata)\n\tslices.SortFunc(svcs, func(a, b *ServicesMetadata) int {\n\t\treturn -cmp.Compare(initOrder[a.serviceName], initOrder[b.serviceName]) // note negative\n\t})\n\tfor _, svc := range svcs {\n\t\tsvc.Stop(ctx)\n\t}\n\n\tif s.so.metricHandler != nil {\n\t\ts.so.metricHandler.Stop(s.logger)","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/temporal/server_impl.go#L85-L121","documentation":"This error wraps any failure that occurs while bootstrap-initializing Temporal's system namespaces during server startup (temporal.Server.Start). The server needs the 'temporal-system' namespace registered in the metadata store before any service can run; if that setup fails at any layer (persistence factory, metadata manager, namespace registration, or the 30s timeout), the whole Start call aborts with this wrapper. It is a startup-time aggregate error, not a runtime error.","triggerScenarios":"Calling temporal.NewServer(...).Start(ctx) when the persistence backend is unreachable or misconfigured, the database schema is not applied, metadataManager.InitializeSystemNamespaces fails (e.g. ER errors writing the temporal-system namespace), or the 30-second namespace-init context times out due to a slow/unresponsive datastore.","commonSituations":"First-time deployment where SQL schemas were never applied (temporal-sql-tool not run); wrong host/port/credentials in persistence config; Cassandra/MySQL/PostgreSQL down or behind a network partition; Elasticsearch visibility misconfiguration; clock/timeout issues where the 30s context deadline expires on a heavily loaded DB.","solutions":["Inspect the wrapped cause (the %w chain printed below this message) — it names the real failure (connection refused, table missing, timeout, etc.)","Run the schema setup tool for your persistence store (temporal-sql-tool / cassandra schema setup) before starting the server","Verify persistence config in config/*.yaml (host, port, user, password, database, plugin) and that the DB is reachable from the server","Check the datastore is not overloaded; the init context is capped at 30 seconds, so resolve DB latency or increase connectivity headroom","If running all-in-one docker/temporalite-style setups, ensure the bundled DB container is healthy before the server starts"],"exampleFix":"// before: server started before DB schema was created\nerr := server.Start(ctx)\n// temporal/server_impl.go:103: unable to initialize system namespace: unable to initialize metadata manager: table namespaces missing\n\n// after: apply schema first, then start\n// temporal-sql-tool --plugin mysql --db temporal setup\n// temporal-sql-tool --plugin mysql --db temporal update-schema -d ./schema/mysql/v57/temporal/versioned\nif err := srv.Start(ctx); err != nil {\n\tlog.Fatal(err)\n}","handlingStrategy":"try-catch","validationCode":"// verify datastore reachability before Start\n// e.g. for mysql:\n// db, err := sql.Open(\"mysql\", dsn)\n// require.NoError(err)\n// require.NoError(db.Ping())\n// and confirm schema tables exist:\n// row := db.QueryRow(\"SELECT count(*) FROM information_schema.tables WHERE table_schema='temporal'\")","typeGuard":null,"tryCatchPattern":"if err := srv.Start(ctx); err != nil {\n\tvar startupErr error\n\tif errors.As(err, &startupErr) {\n\t\tlog.Fatalf(\"system namespace bootstrap failed: %v\", errors.Unwrap(err))\n\t}\n}\n// inspect the wrapped cause to distinguish connectivity vs schema vs timeout","preventionTips":["Always run schema setup/update tools before first server start","Ping the datastore from the server host before deploying","Keep the DB under capacity so the 30s init deadline is never hit","Pin and version your persistence config together with schema versions","Use healthchecks on the DB container before starting the temporal server"],"tags":["startup","persistence","namespace","bootstrap"],"backgroundTag":"persistence-unavailable","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}