temporalio/temporal · error

namespace replication queue not enabled for cluster

Error message

namespace replication queue not enabled for cluster

What it means

Returned by the Admin service's namespace replication queue handler when the frontend's namespaceReplicationQueue dependency is nil, i.e. the cluster was not configured to run the namespace replication queue. The admin API for fetching namespace replication messages/ack levels requires this queue to be enabled.

Source

Thrown at service/frontend/admin_handler.go:1048

		Tokens:      request.GetTokens(),
		ClusterName: request.GetClusterName(),
	})
	if err != nil {
		return nil, err
	}
	return &adminservice.GetReplicationMessagesResponse{ShardMessages: resp.GetShardMessages()}, nil
}

// GetNamespaceReplicationMessages returns new namespace replication tasks since last retrieved task ID.
func (adh *AdminHandler) GetNamespaceReplicationMessages(ctx context.Context, request *adminservice.GetNamespaceReplicationMessagesRequest) (_ *adminservice.GetNamespaceReplicationMessagesResponse, retError error) {
	defer log.CapturePanic(adh.logger, &retError)

	if request == nil {
		return nil, errRequestNotSet
	}

	if adh.namespaceReplicationQueue == nil {
		return nil, errors.New("namespace replication queue not enabled for cluster")
	}

	lastMessageID := request.GetLastRetrievedMessageId()
	if request.GetLastRetrievedMessageId() == defaultLastMessageID {
		if clusterAckLevels, err := adh.namespaceReplicationQueue.GetAckLevels(ctx); err == nil {
			if ackLevel, ok := clusterAckLevels[request.GetClusterName()]; ok {
				lastMessageID = ackLevel
			}
		}
	}

	replicationTasks, lastMessageID, err := adh.namespaceReplicationQueue.GetReplicationMessages(
		ctx,
		lastMessageID,
		getNamespaceReplicationMessageBatchSize,
	)
	if err != nil {
		return nil, err

View on GitHub (pinned to bde624efd1)

Solutions

1. Enable namespace replication queue in the frontend service configuration (global namespaces / replication settings) and restart the frontend
2. Point admin tooling at a cluster that actually participates in namespace replication
3. Check that the cluster is intended to be part of a global namespace setup; if not, the admin call is not applicable

Example fix

// config/temporal.yaml (frontend)
// before
# (namespace replication queue not configured)
// after
frontend:
  namespaces:
    replicationQueue:
      enabled: true

// caller-side check: only call the admin replication API on clusters with replication enabled
if !clusterConfig.EnableGlobalNamespace || !clusterConfig.Frontend.NamespaceReplicationQueueEnabled {
    return errors.New("namespace replication queue not enabled on this cluster")
}

When it happens

Trigger: Calling the admin API (GetNamespaceReplicationMessages / related namespace replication endpoints) on a cluster whose frontend service config did not enable the namespace replication queue.

Common situations: Global-clusters features not enabled (enableGlobalNamespace / replication settings missing in config), running admin tooling against a cluster deployed without cross-cluster namespace replication, or misconfigured service dependencies at frontend startup.

Related errors

• unknown archiver scheme
• unable to find archiver config for the given scheme
• no bucket specified
• empty aws region
• empty BaseURL

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