redis/go-redis · error

redis: unable to parse addr param: %s

Error message

redis: unable to parse addr param: %s

What it means

Each "addr" query parameter of a failover URL must be a valid host:port pair (net.SplitHostPort must succeed and neither host nor port may be empty). Otherwise setupFailoverConnParams returns this error identifying the offending addr string.

Source

Thrown at sentinel.go:521

	o.UnstableResp3 = q.bool("unstable_resp3")

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

	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
	}

	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

View on GitHub (pinned to c5cad058c7)

Solutions

1. Provide full host:port pairs: ?addr=sentinel1:26379&addr=sentinel2:26379
2. For IPv6 use bracketed form: ?addr=[::1]:26379
3. Trim whitespace/extra separators that leave an empty addr entry

Example fix

// before
"redis://mymaster?addr=sentinel-1"          // no port
// after
"redis://mymaster?addr=sentinel-1:26379"

for _, a := range u.Query()["addr"] {
    if h, p, err := net.SplitHostPort(a); err != nil || h == "" || p == "" {
        return fmt.Errorf("addr %q must be host:port", a)
    }
}

opt, err := redis.ParseFailoverURL(raw)
if err != nil {
    if strings.Contains(err.Error(), "unable to parse addr") { /* fix addr params */ }
    return err
}

When it happens

Trigger: ParseFailoverURL with ?addr=localhost (no port), ?addr=:26379 (no host), ?addr=host:port:extra, or an unparseable bracketed IPv6 form.

Common situations: Listing sentinel addresses as bare hostnames without ports, forgetting to URL-encode/merge multiple addresses, or IPv6 addresses whose brackets were stripped by an interpolating config layer.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

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