go-redis/redis · error

redis: unable to parse addr param: %s

Error message

redis: unable to parse addr param: %s

What it means

Returned by setupClusterQueryParams when an ?addr=... query parameter (used to add extra seed nodes to a cluster URL) cannot be split by net.SplitHostPort into a non-empty host and port. Each addr value must be a complete host:port pair.

Source

Thrown at osscluster.go:414

	o.MaxActiveConns = q.int("max_active_conns")
	o.PoolTimeout = q.duration("pool_timeout")
	o.ConnMaxLifetime = q.duration("conn_max_lifetime")
	if q.has("conn_max_lifetime_jitter") {
		o.ConnMaxLifetimeJitter = min(q.duration("conn_max_lifetime_jitter"), o.ConnMaxLifetime)
	}
	o.ConnMaxIdleTime = q.duration("conn_max_idle_time")
	o.FailingTimeoutSeconds = q.int("failing_timeout_seconds")

	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

View on GitHub (pinned to 36d97525cd)

Solutions

1. Make every addr value a full host:port pair.
2. Prefer ClusterOptions.Addrs with net.JoinHostPort to build each entry safely.
3. Validate each addr with net.SplitHostPort before building the URL.

Example fix

// before
opt, err := redis.ParseClusterURL("redis://host:7000/?addr=host2")
// after
opt, err := redis.ParseClusterURL("redis://host:7000/?addr=host2:7000")

func validAddrParam(addr string) bool {
    h, p, err := net.SplitHostPort(addr); return err == nil && h != "" && p != ""
}

When it happens

Trigger: A cluster URL like redis://host:7000/?addr=host2 (missing port) or ?addr=:7000 (missing host) or ?addr=host2:abc (non-numeric port).

Common situations: Copying only the hostname for additional nodes, forgetting the port, or a templating bug that drops the port segment.

Related errors

• redis: invalid URL scheme: %s
• redis: unexpected option: %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/1d12e716594b47c3.json. Report an issue: GitHub.