temporalio/temporal · error

invalid queue name, expected 4 fields

Error message

invalid queue name, expected 4 fields

What it means

ErrInvalidQueueName (common/persistence/history_task_queue_manager.go:46) is returned by GetHistoryTaskQueueCategoryID when a queue name cannot be parsed into the expected 4 fields from which the task category ID is extracted. Queue names encode category, shard, and other identity components; a malformed name means the caller passed a queue identifier the system did not create, or the naming format changed between versions.

Source

Thrown at common/persistence/history_task_queue_manager.go:46

	//	- Blob (a serialized task)
	ErrMsgDeserializeRawHistoryTask = "failed to deserialize raw history task from task queue"
	// ErrMsgDeserializeHistoryTask is returned when the history task cannot be deserialized from the task queue. This
	// error is returned when the blob inside the raw task cannot be deserialized.
	//  Raw Task (a proto):
	//	- ShardID
	//	- Blob (a serialized task) <-- when this cannot be deserialized
	ErrMsgDeserializeHistoryTask = "failed to deserialize history task blob"
	// ErrMsgFailedToParseCategoryID is returned when category id cannot be parsed as an integer value.
	ErrMsgFailedToParseCategoryID = "failed to parse category id from queue name"
)

var (
	ErrReadTasksNonPositivePageSize = errors.New("page size to read history tasks must be positive")
	ErrHistoryTaskBlobIsNil         = errors.New("history task from queue has nil blob")
	ErrEnqueueTaskRequestTaskIsNil  = errors.New("enqueue task request task is nil")
	ErrQueueAlreadyExists           = errors.New("queue already exists")
	ErrShardIDInvalid               = errors.New("shard ID must be greater than 0")
	ErrInvalidQueueName             = errors.New("invalid queue name, expected 4 fields")
)

func NewHistoryTaskQueueManager(
	queue QueueV2,
	serializer serialization.Serializer,
) *HistoryTaskQueueManagerImpl {
	return &HistoryTaskQueueManagerImpl{
		queue:      queue,
		serializer: serializer,
	}
}

func (m *HistoryTaskQueueManagerImpl) EnqueueTask(
	ctx context.Context,
	request *EnqueueTaskRequest,
) (*EnqueueTaskResponse, error) {
	if request.Task == nil {
		return nil, ErrEnqueueTaskRequestTaskIsNil

View on GitHub (pinned to bde624efd1)

Solutions

1. Construct the queue name using the library's queue-name builder/format instead of hand-writing it
2. Check the persisted queue name for version skew and migrate/recreate queues created by incompatible versions
3. Log the offending name and verify it has exactly 4 separator-delimited fields before parsing

Example fix

// before
categoryID, err := persistence.GetHistoryTaskQueueCategoryID("history-task-queue-12") // 3 fields
// after
name := persistence.GetHistoryTaskQueueName(category, shardID, /*expected fields*/) // build via helpers
if strings.Count(name, separator) != 3 {
    return fmt.Errorf("malformed queue name %q", name)
}
categoryID, err := persistence.GetHistoryTaskQueueCategoryID(name)

parts := strings.Split(queueName, separator)
if len(parts) != 4 {
    return fmt.Errorf("queue name %q must have 4 fields, got %d", queueName, len(parts))
}
// safe to call GetHistoryTaskQueueCategoryID

categoryID, err := persistence.GetHistoryTaskQueueCategoryID(queueName)
if err != nil {
    if strings.Contains(err.Error(), "invalid queue name, expected 4 fields") {
        logger.Error("malformed history task queue name", tag.WorkflowQueueName(queueName))
        return err // do not retry: deterministic parse failure
    }
    return err
}

When it happens

Trigger: Calling GetHistoryTaskQueueCategoryID with a queue name that does not split into exactly 4 fields (wrong separator, missing components, or a queue name built by a different/incompatible writer).

Common situations: Hand-constructed queue names in tools/tests; queue names persisted by an older server version being read by a newer one (format change); copying names with typos or extra separators; cross-cluster queue name reuse.

Related errors

• page size to read history tasks must be positive
• enqueue task request task is nil
• shard ID must be greater than 0
• history task from queue has nil blob
• queue already exists

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