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

Use an integer for ?db=N (e.g. ?db=2).

redis: invalid database number: %w

Error message

redis: invalid database number: %w

What it means

Returned by setupConnParams when the legacy ?db=N query parameter is present but cannot be parsed as an integer with strconv.Atoi. Unlike the path DB selector, this wraps the underlying strconv error with %w so the original parse failure is preserved.

Source

Thrown at options.go:845

func (o *queryOptions) remaining() []string {
	if len(o.q) == 0 {
		return nil
	}
	keys := slices.Collect(maps.Keys(o.q))
	slices.Sort(keys)
	return keys
}

// setupConnParams converts query parameters in u to option value in o.
func setupConnParams(u *url.URL, o *Options) (*Options, error) {
	q := queryOptions{q: u.Query()}

	// compat: a future major release may use q.int("db")
	if tmp := q.string("db"); tmp != "" {
		db, err := strconv.Atoi(tmp)
		if err != nil {
			return nil, fmt.Errorf("redis: invalid database number: %w", err)
		}
		o.DB = db
	}

	o.Protocol = q.int("protocol")
	o.ClientName = q.string("client_name")
	o.MaxRetries = q.int("max_retries")
	o.MinRetryBackoff = q.duration("min_retry_backoff")
	o.MaxRetryBackoff = q.duration("max_retry_backoff")
	o.DialTimeout = q.duration("dial_timeout")
	o.ReadTimeout = q.duration("read_timeout")
	o.WriteTimeout = q.duration("write_timeout")
	o.PoolFIFO = q.bool("pool_fifo")
	o.PoolSize = q.int("pool_size")
	o.PoolTimeout = q.duration("pool_timeout")
	o.MinIdleConns = q.int("min_idle_conns")
	o.MaxIdleConns = q.int("max_idle_conns")
	o.MaxActiveConns = q.int("max_active_conns")

View on GitHub (pinned to 36d97525cd)

Solutions

Use an integer for ?db=N (e.g. ?db=2).
Drop the parameter and rely on the path /N or Options.DB.
Validate the value is numeric before assembling the URL.

Example fix

// before
opt, err := redis.ParseURL("redis://localhost:6379/?db=two")
// after
opt, err := redis.ParseURL("redis://localhost:6379/?db=2")

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Use an integer for ?db=N.
Prefer the path form or Options.DB if the value is dynamic.
Validate numeric DB values at config load.

When it happens

Trigger: A URL like redis://host:6379/?db=zero or redis://host:6379/?db=1.0. The db query parameter is the preferred way to set the DB while keeping the path empty.

Common situations: Mistyping the DB index, passing a float, or a templating bug that injects a non-numeric placeholder.

Related errors

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