redis/go-redis · error

redis: unexpected option

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.

Solutions

1. Remove the unknown parameters from the URL
2. Check accepted names: use mastername (not master) and db, addr, skip_verify
3. 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"

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) }
}

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

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

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

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

Appendix: 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)