temporalio/temporal · critical

unable to register system namespace: %w

Error message

unable to register system namespace: %w

What it means

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.

Source

Thrown at temporal/server_impl.go:195

		MetricsHandler:             metricsHandler,
		Logger:                     logger,
		Serializer:                 serializer,
	})
	defer factory.Close()

	metadataManager, err := factory.NewMetadataManager()
	if err != nil {
		return fmt.Errorf("unable to initialize metadata manager: %w", err)
	}
	defer metadataManager.Close()
	ctx, cancel := context.WithTimeout(
		headers.SetCallerInfo(ctx, headers.SystemBackgroundHighCallerInfo),
		30*time.Second,
	)
	defer cancel()

	if err = metadataManager.InitializeSystemNamespaces(ctx, currentClusterName); err != nil {
		return fmt.Errorf("unable to register system namespace: %w", err)
	}
	return nil
}

View on GitHub (pinned to bde624efd1)

Solutions

1. Read the wrapped cause: EntityAlreadyExists vs timeout vs storage error lead to different fixes
2. If it's a timeout, check DB latency/load and network between server and datastore; the operation must finish in 30 seconds
3. 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
4. Ensure only one node performs initial bootstrap or that retries are safe for your persistence backend
5. Re-run schema update if the wrapped error indicates missing/legacy metadata tables

Example fix

// before: two server replicas start simultaneously on an empty DB and race on namespace creation
// docker compose scale temporal=2 -> unable to register system namespace: timeout

// after: run bootstrap once, then scale
// docker compose up -d temporal
// wait for readiness, then:
// docker compose up --scale temporal=3 -d

// confirm metadata store is up and empty-state bootstrap is single-flight:
// if err := db.Ping(); err != nil { return err }
// coordinate bootstrap (e.g. a lock/leader election) so only one node initializes
// system namespaces on a fresh database

err := srv.Start(ctx)
if err != nil && strings.Contains(err.Error(), "unable to register system namespace") {
	// transient storage/timeout errors may be retried; EntityAlreadyExists-style
	// conflicts need inspection instead
	if isTransient(err) { // e.g. deadline exceeded, connection reset
		time.Sleep(5 * time.Second)
		err = srv.Start(ctx)
	}
}
if err != nil { log.Fatal(err) }

When it happens

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

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

Related errors

• unable to initialize system namespace: %w
• unable to get namespace details: %w
• unable to create Elasticsearch client (URL = %v, username =
• error initializing cluster metadata manager: %w
• error while fetching cluster metadata: %w

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