go-redis/redis · error

handoff queue size must be greater than 0

Error message

handoff queue size must be greater than 0

What it means

Returned by Config.Validate() (maintnotifications/config.go:170-172) when Config.HandoffQueueSize is negative. HandoffQueueSize sizes the buffered channel that queues pending connection handoffs (handoff_worker.go:49). The message says 'must be greater than 0' but the actual check is < 0, so 0 is permitted (it triggers auto-calculation); only negatives fail.

Source

Thrown at maintnotifications/errors.go:13

package maintnotifications

import (
	"errors"

	"github.com/redis/go-redis/v9/internal/maintnotifications/logs"
)

// Configuration errors
var (
	ErrInvalidRelaxedTimeout             = errors.New(logs.InvalidRelaxedTimeoutError())
	ErrInvalidHandoffTimeout             = errors.New(logs.InvalidHandoffTimeoutError())
	ErrInvalidHandoffWorkers             = errors.New(logs.InvalidHandoffWorkersError())
	ErrInvalidHandoffQueueSize           = errors.New(logs.InvalidHandoffQueueSizeError())
	ErrInvalidPostHandoffRelaxedDuration = errors.New(logs.InvalidPostHandoffRelaxedDurationError())
	ErrInvalidEndpointType               = errors.New(logs.InvalidEndpointTypeError())
	ErrInvalidMaintNotifications         = errors.New(logs.InvalidMaintNotificationsError())
	ErrMaxHandoffRetriesReached          = errors.New(logs.MaxHandoffRetriesReachedError())

	// Configuration validation errors

	// ErrInvalidHandoffRetries is returned when the number of handoff retries is invalid
	ErrInvalidHandoffRetries = errors.New(logs.InvalidHandoffRetriesError())
)

// Integration errors
var (
	// ErrInvalidClient is returned when the client does not support push notifications
	ErrInvalidClient = errors.New(logs.InvalidClientError())
)

View on GitHub (pinned to 36d97525cd)

Solutions

1. Set HandoffQueueSize to 0 to let the library scale it (max(20*workers, poolSize), capped by MaxActiveConns+1 or 5*poolSize).
2. Set an explicit positive value (minimum 200 is enforced when you set it yourself, per config.go:265).
3. Audit any env/config parsing that can produce negative integers for this field.

Example fix

// before
cfg := &maintnotifications.Config{HandoffQueueSize: -5}

// after
cfg := &maintnotifications.Config{HandoffQueueSize: 0} // auto-scale

if cfg.HandoffQueueSize < 0 {
    cfg.HandoffQueueSize = 0 // auto-scale from pool size
}
if err := cfg.Validate(); err != nil {
    return fmt.Errorf("maint config: %w", err)
}

func validQueueSize(n int) bool { return n >= 0 }

When it happens

Trigger: Setting Options.MaintNotificationsConfig.HandoffQueueSize to a negative number, then constructing the client (which calls Validate()). For example passing a value parsed from an env var or computed as poolSize - someConstant that can go negative for small pools.

Common situations: Operator sets a queue size from a config flag that defaults to -1; a formula like `desired - overhead` underflows for tiny pools; assuming the field required a positive integer when 0 is the 'auto' sentinel.

Related errors

• MaxWorkers must be greater than or equal to 0
• MaxHandoffRetries must be between 1 and 10
• post-handoff relaxed duration must be greater than or equal
• invalid endpoint type
• invalid maintenance notifications setting (must be 'disabled

AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06). Data as JSON: /data/errors/7760be2a6ed7e69b.json. Report an issue: GitHub.