What causes "unable to initialize system namespace: %w" in temporalio/temporal?

Inspect the wrapped cause (the %w chain printed below this message) — it names the real failure (connection refused, table missing, timeout, etc.)

temporalio/temporal · critical

unable to initialize system namespace: %w

Error message

unable to initialize system namespace: %w

What it means

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.

Source

Thrown at temporal/server_impl.go:103

	return s
}

func (s *ServerImpl) Start(ctx context.Context) error {
	s.logger.Info("Starting server for services", tag.Value(s.so.serviceNames))
	s.logger.Debug(s.so.config.String())

	if err := initSystemNamespaces(
		ctx,
		&s.persistenceConfig,
		s.clusterMetadata.CurrentClusterName,
		s.so.persistenceServiceResolver,
		s.persistenceFactoryProvider,
		s.logger,
		s.so.customDataStoreFactory,
		s.metricsHandler,
		s.serializer,
	); err != nil {
		return fmt.Errorf("unable to initialize system namespace: %w", err)
	}

	return s.startServices()
}

func (s *ServerImpl) Stop(ctx context.Context) error {
	close(s.stoppedCh)

	svcs := slices.Clone(s.servicesMetadata)
	slices.SortFunc(svcs, func(a, b *ServicesMetadata) int {
		return -cmp.Compare(initOrder[a.serviceName], initOrder[b.serviceName]) // note negative
	})
	for _, svc := range svcs {
		svc.Stop(ctx)
	}

	if s.so.metricHandler != nil {
		s.so.metricHandler.Stop(s.logger)

View on GitHub (pinned to bde624efd1)

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

Example fix

// before: server started before DB schema was created
err := server.Start(ctx)
// temporal/server_impl.go:103: unable to initialize system namespace: unable to initialize metadata manager: table namespaces missing

// after: apply schema first, then start
// temporal-sql-tool --plugin mysql --db temporal setup
// temporal-sql-tool --plugin mysql --db temporal update-schema -d ./schema/mysql/v57/temporal/versioned
if err := srv.Start(ctx); err != nil {
	log.Fatal(err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

// verify datastore reachability before Start
// e.g. for mysql:
// db, err := sql.Open("mysql", dsn)
// require.NoError(err)
// require.NoError(db.Ping())
// and confirm schema tables exist:
// row := db.QueryRow("SELECT count(*) FROM information_schema.tables WHERE table_schema='temporal'")

Try / catch

if err := srv.Start(ctx); err != nil {
	var startupErr error
	if errors.As(err, &startupErr) {
		log.Fatalf("system namespace bootstrap failed: %v", errors.Unwrap(err))
	}
}
// inspect the wrapped cause to distinguish connectivity vs schema vs timeout

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/14759f13844b92d6. Report an issue: GitHub.