What causes "redis: invalid %s number: %s" in go-redis/redis?

Provide a clean decimal integer for the named parameter.

redis: invalid %s number: %s

Error message

redis: invalid %s number: %s

What it means

Recorded on the queryOptions error slot by queryOptions.int when a query parameter expected to be an integer fails strconv.Atoi. The placeholder is the parameter name (e.g. max_retries, pool_size); the error is surfaced at the end of setupConnParams. Only the first failing parameter is reported.

Source

Thrown at options.go:782

}

func (o *queryOptions) strings(name string) []string {
	vs := o.q[name]
	delete(o.q, name)
	return vs
}

func (o *queryOptions) int(name string) int {
	s := o.string(name)
	if s == "" {
		return 0
	}
	i, err := strconv.Atoi(s)
	if err == nil {
		return i
	}
	if o.err == nil {
		o.err = fmt.Errorf("redis: invalid %s number: %s", name, err)
	}
	return 0
}

func (o *queryOptions) duration(name string) time.Duration {
	s := o.string(name)
	if s == "" {
		return 0
	}
	// try plain number first
	if i, err := strconv.Atoi(s); err == nil {
		if i <= 0 {
			// disable timeouts
			return -1
		}
		return time.Duration(i) * time.Second
	}
	dur, err := time.ParseDuration(s)

View on GitHub (pinned to 36d97525cd)

Solutions

Provide a clean decimal integer for the named parameter.
Remove the parameter to accept the go-redis default.
Run the URL through url.Parse and validate each known int param before constructing the client.

Example fix

// before
opt, err := redis.ParseURL("redis://localhost:6379/?max_retries=three")
// after
opt, err := redis.ParseURL("redis://localhost:6379/?max_retries=3")

Defensive patterns

Strategy: validation

Validate before calling

func validIntParam(s string) bool { _, err := strconv.Atoi(s); return err == nil }

Try / catch

if _, err := redis.ParseURL(raw); err != nil { /* surface the named param in user feedback */ }

Prevention

Keep integer query params to plain decimal digits.
Generate URLs from typed config, not string concatenation.
Document which params are ints vs durations vs bools for ops teams.

When it happens

Trigger: A redis:// or rediss:// URL with a query parameter like ?max_retries=abc, ?pool_size=1.5, or ?protocol=three. Any integer-typed option fed a non-integer string.

Common situations: Typing a unit suffix on an int field (?pool_size=10x), a float value, or a stray character from templating/env substitution.

Related errors

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