go-redis/redis · error

circuit breaker max requests must be >= 1

Error message

circuit breaker max requests must be >= 1

What it means

Returned by Config.Validate() (maintnotifications/config.go:184-186) when Config.CircuitBreakerMaxRequests < 1. This is the number of probe requests allowed through in half-open state to test endpoint recovery (circuit_breaker.go:118). At least one probe is required for the breaker to ever transition back to closed.

Source

Thrown at maintnotifications/errors.go:75

var (
	// ErrShutdown is returned when the maintnotifications manager is shutdown
	ErrShutdown = errors.New(logs.ShutdownError())
)

// circuit breaker errors
var (
	// ErrCircuitBreakerOpen is returned when the circuit breaker is open
	ErrCircuitBreakerOpen = errors.New(logs.CircuitBreakerOpenErrorMessage)
)

// circuit breaker configuration errors
var (
	// ErrInvalidCircuitBreakerFailureThreshold is returned when the circuit breaker failure threshold is invalid
	ErrInvalidCircuitBreakerFailureThreshold = errors.New(logs.InvalidCircuitBreakerFailureThresholdError())
	// ErrInvalidCircuitBreakerResetTimeout is returned when the circuit breaker reset timeout is invalid
	ErrInvalidCircuitBreakerResetTimeout = errors.New(logs.InvalidCircuitBreakerResetTimeoutError())
	// ErrInvalidCircuitBreakerMaxRequests is returned when the circuit breaker max requests is invalid
	ErrInvalidCircuitBreakerMaxRequests = errors.New(logs.InvalidCircuitBreakerMaxRequestsError())
)

View on GitHub (pinned to 36d97525cd)

Solutions

1. Set CircuitBreakerMaxRequests to >=1 (default is 3).
2. For minimal probing use 1; never 0.
3. Clamp externally sourced values to a minimum of 1.

Example fix

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

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

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

func validMaxRequests(n int) bool { return n >= 1 }

When it happens

Trigger: Setting Options.MaintNotificationsConfig.CircuitBreakerMaxRequests to 0 or negative, then constructing the client (Validate runs).

Common situations: Setting it to 0 to 'minimize probe traffic' (instead it breaks validation); computing from a fraction that rounds to 0; stale config.

Related errors

• circuit breaker failure threshold must be >= 1
• circuit breaker reset timeout must be >= 0
• 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

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