go-redis/redis · error

MaxHandoffRetries must be between 1 and 10

Error message

MaxHandoffRetries must be between 1 and 10

What it means

Returned by Config.Validate() (maintnotifications/config.go:199-201) when Config.MaxHandoffRetries is outside the allowed 1-10 range. MaxHandoffRetries bounds how many times a failing connection handoff is retried before the connection is dropped (handoff_worker.go:407). Zero is not allowed because at least one attempt is required; >10 is rejected to prevent runaway retry loops.

Source

Thrown at maintnotifications/errors.go:23

	"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())
)

// Handoff errors
var (
	// ErrHandoffQueueFull is returned when the handoff queue is full
	ErrHandoffQueueFull = errors.New(logs.HandoffQueueFullError())
)

// Notification errors
var (
	// ErrInvalidNotification is returned when a notification is in an invalid format
	ErrInvalidNotification = errors.New(logs.InvalidNotificationError())

View on GitHub (pinned to 36d97525cd)

Solutions

1. Set MaxHandoffRetries to a value between 1 and 10 inclusive (default is 3).
2. If you want maintenance handoffs fully off, set Mode = ModeDisabled rather than zeroing retries.
3. Clamp any externally sourced value into [1,10] before assigning.

Example fix

// before
cfg := &maintnotifications.Config{MaxHandoffRetries: 0}

// after
cfg := &maintnotifications.Config{MaxHandoffRetries: 3}

if cfg.MaxHandoffRetries < 1 || cfg.MaxHandoffRetries > 10 {
    cfg.MaxHandoffRetries = 3
}
if err := cfg.Validate(); err != nil {
    return fmt.Errorf("maint config: %w", err)
}

func validMaxHandoffRetries(n int) bool { return n >= 1 && n <= 10 }

When it happens

Trigger: Setting Options.MaintNotificationsConfig.MaxHandoffRetries to 0 or a value >10, then constructing the client which runs Validate().

Common situations: Setting it to 0 intending 'no retries' (use ModeDisabled instead); bumping it very high to 'never give up' during testing; computing it from a multiplier that overflows the cap.

Related errors

• MaxWorkers must be greater than or equal to 0
• handoff queue size must be greater than 0
• 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/f1162d990b07c35d.json. Report an issue: GitHub.