What causes "redis: unexpected option: %s" in redis/go-redis?

Remove the unknown parameters from the URL

redis: unexpected option: %s

Error message

redis: unexpected option: %s

What it means

After parsing all supported failover-URL query parameters (mastername, db, addr, skip_verify), any leftover parameters are rejected by setupFailoverConnParams with this error listing the unknown names. This catches typos and unsupported options early instead of silently ignoring them.

Source

Thrown at sentinel.go:533

	}

	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.SentinelAddrs = append(o.SentinelAddrs, net.JoinHostPort(h, p))
	}

	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
}

// NewFailoverClient returns a Redis client that uses Redis Sentinel
// for automatic failover. It's safe for concurrent use by multiple
// goroutines.
// Passing nil FailoverOptions will cause a panic.
func NewFailoverClient(failoverOpt *FailoverOptions) *Client {
	if failoverOpt == nil {
		panic("redis: NewFailoverClient nil options")
	}

	if failoverOpt.RouteByLatency {
		panic("to route commands by latency, use NewFailoverClusterClient")
	}
	if failoverOpt.RouteRandomly {

View on GitHub (pinned to c5cad058c7)

Solutions

Remove the unknown parameters from the URL
Check accepted names: use mastername (not master) and db, addr, skip_verify
Set options that aren't URL-supported directly on the returned FailoverOptions struct after parsing

Example fix

// before
"redis://mymaster?addr=s1:26379&master=mymaster"   // wrong param name
// after
"redis://mymaster?addr=s1:26379&mastername=mymaster"

Defensive patterns

Strategy: validation

Validate before calling

allowed := map[string]bool{"mastername": true, "db": true, "addr": true, "skip_verify": true}
u, err := url.Parse(raw)
if err != nil { return err }
for k := range u.Query() {
    if !allowed[k] { return fmt.Errorf("unsupported failover URL param %q", k) }
}

Try / catch

opt, err := redis.ParseFailoverURL(raw)
if err != nil {
    if strings.Contains(err.Error(), "unexpected option") { /* strip or rename params */ }
    return err
}

Prevention

Consult the failover URL docs for the accepted parameter names before hand-writing URLs
Prefer building FailoverOptions in code over long URLs
Add a unit test parsing each connection-string variant you ship

When it happens

Trigger: ParseFailoverURL with unknown or misspelled query params, e.g. ?addr=...&master=mymaster (supported name is mastername) or ?password=secret (not supported on failover URLs).

Common situations: Reusing query params from regular redis:// URL docs that don't apply to the failover parser, typos like addrs= or tls=, and params added by secret-injection tooling.

Related errors

AI-assisted analysis of redis/go-redis@c5cad058c7 (2026-09-01). Data as JSON: /api/errors/a21ee54e8915f766. Report an issue: GitHub.