go-redis/redis · error

invalid maintenance notifications setting (must be 'disabled

Error message

invalid maintenance notifications setting (must be 'disabled', 'enabled', or 'auto')

What it means

Returned by Config.Validate() (maintnotifications/config.go:189-191) when Config.Mode is not one of the three valid modes. Mode controls how the client negotiates the CLIENT MAINT_NOTIFICATIONS ON handshake: ModeDisabled (off), ModeEnabled (require server support, fail hard if missing), ModeAuto (try then silently disable) — defined at config.go:17-21.

Source

Thrown at maintnotifications/errors.go:16

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

// Handoff errors
var (
	// ErrHandoffQueueFull is returned when the handoff queue is full

View on GitHub (pinned to 36d97525cd)

Solutions

1. Use a typed Mode constant: maintnotifications.ModeAuto (default), ModeEnabled, or ModeDisabled.
2. When wiring from a config value, normalize booleans/strings into one of the three constants explicitly.
3. Call Mode.IsValid() (config.go:24) early to produce a targeted error.

Example fix

// before
cfg := &maintnotifications.Config{Mode: maintnotifications.Mode("true")}

// after
cfg := &maintnotifications.Config{Mode: maintnotifications.ModeAuto}

if !cfg.Mode.IsValid() {
    cfg.Mode = maintnotifications.ModeAuto
}
if err := cfg.Validate(); err != nil {
    return fmt.Errorf("maint config: %w", err)
}

func validMode(m maintnotifications.Mode) bool { return m.IsValid() }

When it happens

Trigger: Assigning a custom Mode string (e.g. 'on', 'true', 'yes', 'force') to Options.MaintNotificationsConfig.Mode, then constructing a client that triggers Validate().

Common situations: Mapping a boolean 'enable_maint_notifications=true' env flag to the Mode string 'true'; a typo like 'enable' vs 'enabled'; an older docs example using a since-renamed value.

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
• MaxHandoffRetries must be between 1 and 10

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