go-redis/redis · error

redis: unexpected option: %s

Error message

redis: unexpected option: %s

What it means

Returned by setupConnParams when, after consuming all recognised query parameters, some keys remain in the URL query string. go-redis treats unknown query parameters as an error rather than silently ignoring them, listing every leftover key joined by commas.

Source

Thrown at options.go:887

	}
	if q.has("conn_max_lifetime") {
		o.ConnMaxLifetime = q.duration("conn_max_lifetime")
	} else {
		o.ConnMaxLifetime = q.duration("max_conn_age")
	}
	if q.has("conn_max_lifetime_jitter") {
		o.ConnMaxLifetimeJitter = min(q.duration("conn_max_lifetime_jitter"), o.ConnMaxLifetime)
	}
	if q.err != nil {
		return nil, q.err
	}
	if o.TLSConfig != nil && q.has("skip_verify") {
		o.TLSConfig.InsecureSkipVerify = q.bool("skip_verify")
	}

	// any parameters left?
	if r := q.remaining(); len(r) > 0 {
		return nil, fmt.Errorf("redis: unexpected option: %s", strings.Join(r, ", "))
	}

	return o, nil
}

func getUserPassword(u *url.URL) (string, string) {
	var user, password string
	if u.User != nil {
		user = u.User.Username()
		if p, ok := u.User.Password(); ok {
			password = p
		}
	}
	return user, password
}

func newConnPool(
	opt *Options,

View on GitHub (pinned to 36d97525cd)

Solutions

1. Map the leftover key to the supported snake_case name (see the ParseURL doc comment for the full list).
2. Remove the parameter if it is no longer relevant.
3. Set the option programmatically on *redis.Options if there is no URL equivalent.

Example fix

// before
opt, err := redis.ParseURL("redis://localhost:6379/?poolsize=10")
// after
opt, err := redis.ParseURL("redis://localhost:6379/?pool_size=10")

var knownStandaloneParams = map[string]bool{
    "db": true, "protocol": true, "client_name": true, "max_retries": true,
    "min_retry_backoff": true, "max_retry_backoff": true, "dial_timeout": true,
    "read_timeout": true, "write_timeout": true, "pool_fifo": true,
    "pool_size": true, "pool_timeout": true, "min_idle_conns": true,
    "max_idle_conns": true, "max_active_conns": true, "max_concurrent_dials": true,
    "conn_max_idle_time": true, "idle_timeout": true, "conn_max_lifetime": true,
    "max_conn_age": true, "conn_max_lifetime_jitter": true, "skip_verify": true,
}
func unknownParams(u *url.URL) []string {
    var unk []string
    for k := range u.Query() { if !knownStandaloneParams[k] { unk = append(unk, k) } }
    return unk
}

When it happens

Trigger: A URL like redis://host:6379/?timeout=5s (timeout is not a valid option; the real names are read_timeout/write_timeout), or redis://host:6379/?ssl=true (use rediss:// or skip_verify). Also triggered by misspelling a supported name like ?poolsize=10 (correct: pool_size).

Common situations: Carrying over options from another Redis client's URL format, typos in snake_case names, or deprecated names no longer accepted.

Related errors

• redis: invalid URL scheme: %s
• redis: invalid database number: %q
• redis: invalid URL path: %s
• redis: invalid %s number: %s
• redis: invalid %s duration: %w

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