go-redis/redis · error
redis: %s value %d exceeds maximum allowed value %d
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.
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)
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: %s value %d is below minimum allowed value %d
- 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
AI-assisted analysis of go-redis/redis@36d97525cd (2026-08-06).
Data as JSON: /data/errors/f21fe35dbbaebe0b.json.
Report an issue: GitHub.