temporalio/temporal · error

error initializing cluster metadata manager: %w

Error message

error initializing cluster metadata manager: %w

What it means

Wraps an error from factory.NewClusterMetadataManager() during persistence bootstrap (cluster metadata provider in the FX graph). The cluster metadata manager is the persistence-layer accessor for cluster metadata records; failure here means the persistence factory could not build that manager (bad driver config, connection failure, or unsupported store).

Source

Thrown at temporal/fx.go:682

		metricsHandler,
		telemetry.NoopTracerProvider,
		serializer,
	)
	factory := persistenceFactoryProvider(persistenceClient.NewFactoryParams{
		DataStoreFactory:           dataStoreFactory,
		Cfg:                        &svc.Persistence,
		PersistenceMaxQPS:          nil,
		PersistenceNamespaceMaxQPS: nil,
		ClusterName:                persistenceClient.ClusterName(svc.ClusterMetadata.CurrentClusterName),
		MetricsHandler:             metricsHandler,
		Logger:                     logger,
		Serializer:                 serializer,
	})
	defer factory.Close()

	clusterMetadataManager, err := factory.NewClusterMetadataManager()
	if err != nil {
		return svc.ClusterMetadata, svc.Persistence, fmt.Errorf("error initializing cluster metadata manager: %w", err)
	}
	defer clusterMetadataManager.Close()

	visCSAOverride := map[enumspb.IndexedValueType]int{}
	for tpName, value := range svc.Visibility.PersistenceCustomSearchAttributes {
		saType, ok := enumspb.IndexedValueType_shorthandValue[tpName]
		if !ok {
			return svc.ClusterMetadata,
				svc.Persistence,
				fmt.Errorf("invalid search attribute type: %s", tpName)
		}
		if value < 0 || value > 99 {
			return svc.ClusterMetadata,
				svc.Persistence,
				fmt.Errorf(
					"invalid number of custom search attributes for type %s (must be between 0 and 99)",
					tpName,
				)

View on GitHub (pinned to bde624efd1)

Solutions

1. Read the wrapped root error for the driver-specific cause
2. Verify the clusterMetadata persistence datastore is reachable and credentials are correct
3. Confirm the persistence type (cassandra/postgres/mysql/sqlite) is supported and schema is applied
4. Run temporal-sql-tool / temporal-cassandra-tool to validate schema connectivity

// pre-check connectivity before starting the server
if err := pingDatastore(cfg.Persistence.DataStores[store]); err != nil {
    return err
}

if err := startServer(opts); err != nil {
    // root cause is wrapped; inspect with errors.As/Unwrap
    return fmt.Errorf("cluster metadata manager init: %w", err)
}

When it happens

Trigger: Starting the server when the persistence datastore backing cluster metadata cannot construct a ClusterMetadataManager — e.g. unreachable Cassandra/SQL database, unsupported persistence type, or driver init error.

Common situations: Database down or wrong host/port in persistence config; unsupported store driver for cluster metadata; bad credentials preventing the driver from initializing schema access.

Related errors

• error while fetching cluster metadata: %w
• error while loading metadata from cluster: %w
• unable to initialize metadata manager: %w
• failed to initialize current cluster metadata
• missing current cluster metadata under clusterMetadata.Clust

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