go-redis/redis · error

redis: unexpected option: %s

Error message

redis: unexpected option: %s

What it means

Returned by setupClusterQueryParams when query parameters remain after all recognised cluster options are consumed. Same strictness as the standalone path: unknown cluster URL query keys are an error, listed comma-separated.

Source

Thrown at osscluster.go:422

	if q.err != nil {
		return nil, q.err
	}

	// addr can be specified as many times as needed
	addrs := q.strings("addr")
	for _, addr := range addrs {
		h, p, err := net.SplitHostPort(addr)
		if err != nil || h == "" || p == "" {
			return nil, fmt.Errorf("redis: unable to parse addr param: %s", addr)
		}

		o.Addrs = append(o.Addrs, net.JoinHostPort(h, p))
	}

	// 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 (opt *ClusterOptions) clientOptions() *Options {
	// Clone MaintNotificationsConfig to avoid sharing between cluster node clients
	var maintNotificationsConfig *maintnotifications.Config
	if opt.MaintNotificationsConfig != nil {
		configClone := *opt.MaintNotificationsConfig
		maintNotificationsConfig = &configClone
	}

	return &Options{
		ClientName: opt.ClientName,
		Dialer:     opt.Dialer,
		OnConnect:  opt.OnConnect,

View on GitHub (pinned to 36d97525cd)

Solutions

1. Rename the leftover key to the supported snake_case name (see setupClusterQueryParams for the accepted set).
2. Remove the unsupported parameter.
3. Set the value on *redis.ClusterOptions directly if there is no URL equivalent.

Example fix

// before
opt, err := redis.ParseClusterURL("redis://host:7000/?maxredirects=5")
// after
opt, err := redis.ParseClusterURL("redis://host:7000/?max_redirects=5")

var knownClusterParams = map[string]bool{
    "addr": true, "protocol": true, "client_name": true, "max_redirects": true,
    "read_only": true, "route_by_latency": true, "route_randomly": true,
    "max_retries": true, "min_retry_backoff": true, "max_retry_backoff": true,
    "dial_timeout": true, "dialer_retries": true, "dialer_retry_timeout": true,
    "read_timeout": true, "write_timeout": true, "pool_fifo": true,
    "pool_size": true, "max_concurrent_dials": true, "min_idle_conns": true,
    "max_idle_conns": true, "max_active_conns": true, "pool_timeout": true,
    "conn_max_lifetime": true, "conn_max_lifetime_jitter": true,
    "conn_max_idle_time": true, "failing_timeout_seconds": true,
}

When it happens

Trigger: A cluster URL like redis://host:7000/?shards=3 (no such option) or redis://host:7000/?maxredirects=5 (correct name is max_redirects). Any unrecognised snake_case key triggers it.

Common situations: Typos in option names, options carried over from another driver, or parameters that only exist on the standalone Options (e.g. min_idle_conns is supported, but many arbitrary keys are not).

Related errors

• redis: invalid URL scheme: %s
• redis: unable to parse addr param: %s
• redis: invalid URL scheme: %s
• redis: invalid database number: %q
• redis: invalid URL path: %s

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