go-redis/redis · error

to route commands by latency, use NewFailoverClusterClient

Error message

to route commands by latency, use NewFailoverClusterClient

What it means

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

Source

Thrown at sentinel.go:540

	// 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 {
		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()

View on GitHub (pinned to 36d97525cd)

Solutions

1. Use NewFailoverClusterClient when RouteByLatency routing is required
2. Disable RouteByLatency for the simple failover client

When it happens

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

Common situations: Match routing options to the client constructor that supports them.

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