go-redis/redis · error

redis: %s value %d is below minimum allowed value %d

Error message

redis: %s value %d is below minimum allowed value %d

What it means

Returned by util.SafeIntToInt32 when an int value is below math.MinInt32 (-2,147,483,648). Same path as the overflow case; it guards the negative bound before the int->int32 cast used for pool sizing fields. Negative pool sizes are nonsensical, so this surfaces a malformed config.

Source

Thrown at internal/util/convert.go:38

	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

1. Use a non-negative value for the pool option.
2. Validate config at load time and reject values < 0 for these fields.
3. Set the field to 0 to take the go-redis default.

Example fix

// before
opt := &redis.Options{MinIdleConns: -(1 << 33)}
// after
opt := &redis.Options{MinIdleConns: 10}

func nonNegPoolInt(v int) (int32, error) {
    if v < 0 { return 0, fmt.Errorf("pool field must be >= 0, got %d", v) }
    return util.SafeIntToInt32(v, "pool")
}

func isValidPoolInt(v int) bool { return v >= 0 && v <= math.MaxInt32 }

When it happens

Trigger: Setting a pool option (PoolSize/MinIdleConns/MaxIdleConns/MaxActiveConns) to a large negative number whose magnitude exceeds MinInt32, or directly calling util.SafeIntToInt32 with such a value.

Common situations: A signed arithmetic bug producing a very large negative, or an uninitialised/garbage config value interpreted as int. Far rarer than the overflow case since negative pool sizes are already invalid.

Related errors

• redis: %s value %d exceeds maximum 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/e810c4334ae3b790.json. Report an issue: GitHub.