go-redis/redis · error
redis: value exceeds maximum allowed value
Error message
redis: %s value %d exceeds maximum allowed value %d
What it means
Returned by util.SafeIntToInt32 when an int value exceeds math.MaxInt32 (2,147,483,647). go-redis uses it in newConnPool/newPubSubPool to clamp pool sizing fields (PoolSize, MinIdleConns, MaxIdleConns, MaxActiveConns) into the int32 the internal pool struct expects. The fieldName in the message identifies which option overflowed.
Solutions
- Cap the offending option at a sane value (PoolSize in the low thousands is already extreme).
- If the value comes from env/config, validate and clamp it before assigning to Options.
- Leave the option at 0 so go-redis applies its default (10*GOMAXPROCS for PoolSize).
Example fix
// before
opt := &redis.Options{PoolSize: 1 << 40}
// after
opt := &redis.Options{PoolSize: 1000} Defensive patterns
Strategy: validation
Validate before calling
func clampPoolField(name string, v int) (int32, error) {
return util.SafeIntToInt32(v, name)
}
// before building the client:
if _, err := util.SafeIntToInt32(opt.PoolSize, "PoolSize"); err != nil { return err } Type guard
func isValidPoolInt(v int) bool { return v >= math.MinInt32 && v <= math.MaxInt32 } Prevention
- Treat pool sizes as small counts; never derive them from byte magnitudes.
- Clamp env-derived pool config to a sane maximum before assigning.
- Leave the field 0 to accept the go-redis default unless you have measured a need.
When it happens
Trigger: Constructing a Client/PubSub pool on a 64-bit host with a pool option set above MaxInt32, e.g. Options{PoolSize: 1 << 40} or reading such a value from config/env. Any caller of util.SafeIntToInt32 passing an out-of-range int.
Common situations: Mis-scaled config (multiplying by a factor that blows past 2^31), an env var parsed as a raw large number, or a bug where bytes vs counts get confused. Practically only reachable on 64-bit builds since int is 32-bit elsewhere.
Related errors
- redis: value is below minimum allowed value
- circuit breaker failure threshold must be >= 1
- circuit breaker max requests must be >= 1
- circuit breaker reset timeout must be >= 0
- handoff queue size must be greater than 0
AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06).
Data as JSON: /api/errors/f21fe35dbbaebe0b.
Report an issue: GitHub.
Appendix: source
Thrown at internal/util/convert.go:35
case "nan", "-nan":
return math.NaN(), nil
}
return strconv.ParseFloat(s, 64)
}
// MustParseFloat is like ParseFloat but panics on parse errors.
func MustParseFloat(s string) float64 {
f, err := ParseStringToFloat(s)
if err != nil {
panic(fmt.Sprintf("redis: failed to parse float %q: %v", s, err))
}
return f
}
// SafeIntToInt32 safely converts an int to int32, returning an error if overflow would occur.
func SafeIntToInt32(value int, fieldName string) (int32, error) {
if value > math.MaxInt32 {
return 0, fmt.Errorf("redis: %s value %d exceeds maximum allowed value %d", fieldName, value, math.MaxInt32)
}
if value < math.MinInt32 {
return 0, fmt.Errorf("redis: %s value %d is below minimum allowed value %d", fieldName, value, math.MinInt32)
}
return int32(value), nil
}
View on GitHub (pinned to 36d97525cd)