temporalio/temporal · error

cannot handle replication task of type %v

Error message

cannot handle replication task of type %v

What it means

The replication message processor's handleReplicationTask dispatches on task.TaskType; when it receives a task type it has no case for and no customTaskHandler is configured, it returns this error, causing the replication task to fail and be retried/nacked.

Source

Thrown at service/worker/replicator/replication_message_processor.go:342

			p.logger.Error("unable to process namespace replication task",
				tag.WorkflowNamespaceID(attr.Id),
				tag.Error(err))
		}
		return err
	case enumsspb.REPLICATION_TASK_TYPE_TASK_QUEUE_USER_DATA:
		attr := task.GetTaskQueueUserDataAttributes()
		err := p.handleTaskQueueUserDataReplicationTask(ctx, attr)
		if err != nil {
			p.logger.Error(fmt.Sprintf("unable to process task queue metadata replication task, %v", attr.TaskQueueName),
				tag.WorkflowNamespaceID(attr.NamespaceId),
				tag.Error(err))
		}
		return err
	default:
		if p.customTaskHandler != nil {
			return p.customTaskHandler(ctx, task)
		}
		return fmt.Errorf("cannot handle replication task of type %v", task.TaskType)
	}
}

func (p *replicationMessageProcessor) handleTaskQueueUserDataReplicationTask(
	ctx context.Context,
	attrs *replicationspb.TaskQueueUserDataAttributes,
) error {
	_, err := p.namespaceRegistry.GetNamespaceByID(namespace.ID(attrs.GetNamespaceId()))
	switch err.(type) {
	case nil:
	case *serviceerror.NamespaceNotFound:
		// The namespace in the request isn't registered on this cluster, drop the replication task.
		// This is okay and enables using the cluster-global replication queue to replicate different namespaces to
		// different sets of clusters.
		// When this cluster is added to the list of replicated clusters for this namespace on the origin cluster, the
		// force replication workflow should be triggered to seed the namespace replication queue with all task queue
		// user data entries for the namespace.
		return nil

View on GitHub (pinned to bde624efd1)

Solutions

1. Upgrade the replicator/worker binary to a version that knows the new task type.
2. Register a customTaskHandler via the processor configuration to handle unknown task types during rollouts.
3. Check for version skew between history (producer) and worker (consumer) and align deployments.
4. Inspect logs for the offending TaskType value and map it to the newer protocol feature.

Example fix

// before
if p.customTaskHandler != nil {
    return p.customTaskHandler(ctx, task)
}
return fmt.Errorf("cannot handle replication task of type %v", task.TaskType)
// after
if p.customTaskHandler != nil {
    return p.customTaskHandler(ctx, task)
}
return fmt.Errorf("cannot handle replication task of type %v: upgrade replicator to a version supporting this task type", task.TaskType)

// configure the processor with a custom handler before starting
processor, err := NewReplicationMessageProcessor(opts)
if err != nil {
    return fmt.Errorf("processor init: %w", err)
}
processor.SetCustomTaskHandler(handleUnknownTaskType)

err := processor.Run(ctx)
var appErr *temporal.ApplicationError
if errors.As(err, &appErr) && strings.Contains(err.Error(), "cannot handle replication task of type") {
    // non-retryable: trigger upgrade/alert instead of hot-looping
}

When it happens

Trigger: A replication task with a TaskType unknown to this processor version arrives (e.g. a new replication attribute type introduced in a newer server version) and p.customTaskHandler is nil.

Common situations: Version skew: history service on a newer release emits a new replication task type while the worker/replicator binary is older; deployment rollouts where replicator pods lag behind history pods; custom task handler not registered in the processor setup.

Related errors

• unknown archetypeID: %v
• task queue user data replication failed: %v
• Unknown repication task type: %v
• %w: state namespace failover version < ref namespace failove
• %w: state namespace failover version > ref namespace failove

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