go-redis/redis · error

MaxWorkers must be greater than or equal to 0

Error message

MaxWorkers must be greater than or equal to 0

What it means

Returned by Config.Validate() (maintnotifications/config.go:166-168) when the maintenance-notifications Config.MaxWorkers is set to a negative value. MaxWorkers controls how many on-demand goroutines process connection handoffs during Redis maintenance events (MOVING/MIGRATING). Despite the message, 0 is valid (it triggers auto-calculation based on pool size); only negative values are rejected.

Source

Thrown at maintnotifications/errors.go:12

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 MaxWorkers to 0 (or omit it) to let the library auto-calculate from pool size (config.go applyWorkerDefaults uses min(poolSize/2, max(10, poolSize/3))).
2. If tuning manually, set MaxWorkers to a positive integer (>=1); any value >=0 passes validation.
3. Search your config plumbing for any place that uses -1 as an 'unset' marker and convert it to 0 before passing into the maint Config.

Example fix

// before
cfg := &maintnotifications.Config{MaxWorkers: -1}
if err := cfg.Validate(); err != nil { panic(err) } // ErrInvalidHandoffWorkers

// after
// leave zero-valued or set explicitly; 0 means auto-calculate
cfg := &maintnotifications.Config{MaxWorkers: 0}

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

// MaxWorkers is an int; guard its domain before use.
func validMaxWorkers(n int) bool { return n >= 0 }

When it happens

Trigger: Constructing a Client/ClusterClient whose Options.MaintNotificationsConfig.MaxWorkers is explicitly set below 0, which causes Validate() to return ErrInvalidHandoffWorkers during client init. The validation runs as part of config ApplyDefaults/Validate before the manager is created (manager.go:126).

Common situations: A config file or env-derived integer that defaults to -1 as a sentinel; arithmetic that computes worker count from a subtracted pool size; copy-pasting a tuning recipe that assumed 0 was invalid.

Related errors

• handoff queue size must be greater than 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/23ab3e728e2ca4f4.json. Report an issue: GitHub.