go-redis/redis · error

to route commands randomly, use NewFailoverClusterClient

Error message

to route commands randomly, use NewFailoverClusterClient

What it means

Error "to route commands randomly, use NewFailoverClusterClient" thrown in go-redis/redis.

Source

Thrown at sentinel.go:543

	}

	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 {
		panic("to route commands randomly, use NewFailoverClusterClient")
	}

	sentinelAddrs := make([]string, len(failoverOpt.SentinelAddrs))
	copy(sentinelAddrs, failoverOpt.SentinelAddrs)

	rand.Shuffle(len(sentinelAddrs), func(i, j int) {
		sentinelAddrs[i], sentinelAddrs[j] = sentinelAddrs[j], sentinelAddrs[i]
	})

	failover := &sentinelFailover{
		opt:           failoverOpt,
		sentinelAddrs: sentinelAddrs,
	}

	opt := failoverOpt.clientOptions()
	opt.Dialer = masterReplicaDialer(failover)
	opt.init()

View on GitHub (pinned to 36d97525cd)

Solutions

1. Use NewFailoverClusterClient for RouteRandomly routing
2. Disable RouteRandomly for the simple failover client

When it happens

Trigger: Thrown at sentinel.go:543 when the library encounters an invalid state.

Common situations: Validate routing flags against the chosen client type.

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