{"record":{"id":"c992a01ba239c593","repo":"temporalio/temporal","slug":"cannot-handle-replication-task-of-type-v","errorCode":null,"errorMessage":"cannot handle replication task of type %v","messagePattern":"cannot handle replication task of type (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/worker/replicator/replication_message_processor.go","lineNumber":342,"sourceCode":"\t\t\tp.logger.Error(\"unable to process namespace replication task\",\n\t\t\t\ttag.WorkflowNamespaceID(attr.Id),\n\t\t\t\ttag.Error(err))\n\t\t}\n\t\treturn err\n\tcase enumsspb.REPLICATION_TASK_TYPE_TASK_QUEUE_USER_DATA:\n\t\tattr := task.GetTaskQueueUserDataAttributes()\n\t\terr := p.handleTaskQueueUserDataReplicationTask(ctx, attr)\n\t\tif err != nil {\n\t\t\tp.logger.Error(fmt.Sprintf(\"unable to process task queue metadata replication task, %v\", attr.TaskQueueName),\n\t\t\t\ttag.WorkflowNamespaceID(attr.NamespaceId),\n\t\t\t\ttag.Error(err))\n\t\t}\n\t\treturn err\n\tdefault:\n\t\tif p.customTaskHandler != nil {\n\t\t\treturn p.customTaskHandler(ctx, task)\n\t\t}\n\t\treturn fmt.Errorf(\"cannot handle replication task of type %v\", task.TaskType)\n\t}\n}\n\nfunc (p *replicationMessageProcessor) handleTaskQueueUserDataReplicationTask(\n\tctx context.Context,\n\tattrs *replicationspb.TaskQueueUserDataAttributes,\n) error {\n\t_, err := p.namespaceRegistry.GetNamespaceByID(namespace.ID(attrs.GetNamespaceId()))\n\tswitch err.(type) {\n\tcase nil:\n\tcase *serviceerror.NamespaceNotFound:\n\t\t// The namespace in the request isn't registered on this cluster, drop the replication task.\n\t\t// This is okay and enables using the cluster-global replication queue to replicate different namespaces to\n\t\t// different sets of clusters.\n\t\t// When this cluster is added to the list of replicated clusters for this namespace on the origin cluster, the\n\t\t// force replication workflow should be triggered to seed the namespace replication queue with all task queue\n\t\t// user data entries for the namespace.\n\t\treturn nil","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/temporalio/temporal/blob/bde624efd13fbd3843654058db6d9c716166318b/service/worker/replicator/replication_message_processor.go#L324-L360","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the replicator/worker binary to a version that knows the new task type.","Register a customTaskHandler via the processor configuration to handle unknown task types during rollouts.","Check for version skew between history (producer) and worker (consumer) and align deployments.","Inspect logs for the offending TaskType value and map it to the newer protocol feature."],"exampleFix":"// before\nif p.customTaskHandler != nil {\n    return p.customTaskHandler(ctx, task)\n}\nreturn fmt.Errorf(\"cannot handle replication task of type %v\", task.TaskType)\n// after\nif p.customTaskHandler != nil {\n    return p.customTaskHandler(ctx, task)\n}\nreturn fmt.Errorf(\"cannot handle replication task of type %v: upgrade replicator to a version supporting this task type\", task.TaskType)","handlingStrategy":"fallback","validationCode":"// configure the processor with a custom handler before starting\nprocessor, err := NewReplicationMessageProcessor(opts)\nif err != nil {\n    return fmt.Errorf(\"processor init: %w\", err)\n}\nprocessor.SetCustomTaskHandler(handleUnknownTaskType)","typeGuard":null,"tryCatchPattern":"err := processor.Run(ctx)\nvar appErr *temporal.ApplicationError\nif errors.As(err, &appErr) && strings.Contains(err.Error(), \"cannot handle replication task of type\") {\n    // non-retryable: trigger upgrade/alert instead of hot-looping\n}","preventionTips":["Always deploy replicator/worker upgrades before or atomically with history upgrades.","Register a customTaskHandler as a safety net for unknown task types during rollouts.","Track new replication task types in release notes and add cases proactively.","Alert on this error — it is a strong version-skew signal."],"tags":["go","temporal","replication","version-skew","task-processor"],"backgroundTag":"unsupported-replication-task-type","analyzedSha":"bde624efd13fbd3843654058db6d9c716166318b","analyzedAt":"2026-09-01T07:18:39.080Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}