go-redis/redis · error

circuit breaker failure threshold must be >= 1

Error message

circuit breaker failure threshold must be >= 1

What it means

Returned by Config.Validate() (maintnotifications/config.go:178-180) when Config.CircuitBreakerFailureThreshold < 1. This threshold is the number of handoff failures to an endpoint required to open its circuit breaker (circuit_breaker.go:145). At least one failure must be required, otherwise the breaker could never open.

Source

Thrown at maintnotifications/errors.go:71

	ErrConnectionInvalidHandoffState = errors.New(logs.ConnectionInvalidHandoffStateErrorMessage)
)

// shutdown errors
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 CircuitBreakerFailureThreshold to >=1 (default is 5).
2. To make the breaker very sensitive, use a low positive value like 1-3, never 0.
3. Clamp externally sourced values to a minimum of 1 before assigning.

Example fix

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

// after
cfg := &maintnotifications.Config{CircuitBreakerFailureThreshold: 5}

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

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

When it happens

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

Common situations: Setting it to 0 intending to 'disable' the breaker (it does not — it just fails validation); computing it from a ratio that underflows; copy-pasting a stale config.

Related errors

• circuit breaker reset timeout must be >= 0
• circuit breaker max requests must be >= 1
• 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/9f732fadcfeffbd8.json. Report an issue: GitHub.