What causes "page size to read history tasks must be positive" in temporalio/temporal?

Set PageSize to a positive value (e.g. the configured task fetch batch size) before calling ReadRawTasks

page size to read history tasks must be positive

Error message

page size to read history tasks must be positive

What it means

ErrReadTasksNonPositivePageSize (common/persistence/history_task_queue_manager.go:41) is a public sentinel guarding ReadRawTasks on HistoryTaskQueueManagerImpl. Reading history tasks from a task queue requires a strictly positive page size; a zero or negative value is an invalid request and is rejected immediately. A matching unit test (TestHistoryTaskQueueManager_ReadTasks_NonPositivePageSize) and the queue Invoke path assert this behavior.

Source

Thrown at common/persistence/history_task_queue_manager.go:41

	ErrMsgSerializeTaskToEnqueue = "failed to serialize history task for task queue"
	// ErrMsgDeserializeRawHistoryTask is returned when the raw task cannot be deserialized from the task queue. This error
	// is returned when this whole top-level proto cannot be deserialized.
	//  Raw Task (a proto): <-- when this cannot be deserialized
	//	- ShardID
	//	- 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(

View on GitHub (pinned to bde624efd1)

Solutions

Set PageSize to a positive value (e.g. the configured task fetch batch size) before calling ReadRawTasks
Clamp/validate the page size at the caller: if ps <= 0 { ps = defaultPageSize }
Fix the config/struct initialization that left PageSize unset

Example fix

// before
resp, err := mgr.ReadRawTasks(ctx, &persistence.ReadHistoryTasksRequest{PageSize: 0})
// after
pageSize := cfg.PageSize
if pageSize <= 0 {
    pageSize = 100
}
resp, err := mgr.ReadRawTasks(ctx, &persistence.ReadHistoryTasksRequest{PageSize: pageSize})

Defensive patterns

Strategy: validation

Validate before calling

if req.PageSize <= 0 {
    return fmt.Errorf("ReadRawTasks requires positive page size, got %d", req.PageSize)
}
// safe to call ReadRawTasks

Try / catch

resp, err := mgr.ReadRawTasks(ctx, req)
if err != nil {
    if strings.Contains(err.Error(), "page size to read history tasks must be positive") {
        req.PageSize = defaultHistoryTaskPageSize
        resp, err = mgr.ReadRawTasks(ctx, req)
    }
    if err != nil { return err }
}

Prevention

Always initialize PageSize explicitly in ReadHistoryTasksRequest structs
Centralize page-size defaults in one config constant
Never derive page size from arithmetic that can reach <= 0 without clamping

When it happens

Trigger: Calling ReadRawTasks (or the queue ReadTasks path via Invoke) with a request whose PageSize is 0 or negative.

Common situations: Uninitialized request struct defaulting PageSize to 0; caller code copying a page size from a config that failed to load; loop logic computing a remaining-page size that hits 0 or below before the terminal page.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

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