go-redis/redis · error

redis: the shard is not in the ring

Error message

redis: the shard is not in the ring

What it means

Returned by ringSharding.GetByName when a specific shard name is requested but is not present in the current shards map. This happens when a shard was removed during a rebalance/reconfiguration or the name doesn't match any configured shard. GetByName is used internally and when callers target a shard by name.

Source

Thrown at ring.go:505

	shardName := c.hash.Get(key)
	if shardName == "" {
		return nil, errRingShardsDown
	}
	return c.shards.m[shardName], nil
}

func (c *ringSharding) GetByName(shardName string) (*ringShard, error) {
	if shardName == "" {
		return c.Random()
	}

	c.mu.RLock()
	defer c.mu.RUnlock()

	shard, ok := c.shards.m[shardName]
	if !ok {
		return nil, errors.New("redis: the shard is not in the ring")
	}

	return shard, nil
}

func (c *ringSharding) Random() (*ringShard, error) {
	return c.GetByKey(strconv.Itoa(rand.Int()))
}

// Heartbeat monitors state of each shard in the ring.
func (c *ringSharding) Heartbeat(ctx context.Context, frequency time.Duration) {
	ticker := time.NewTicker(frequency)
	defer ticker.Stop()

	for {
		select {
		case <-ticker.C:
			var rebalance bool

View on GitHub (pinned to 36d97525cd)

Solutions

1. Verify the shard name matches a key in RingOptions.Addrs exactly.
2. If shards are reconfigured at runtime, ensure in-flight operations complete or retry against the updated ring.
3. Check heartbeat/rebalance logs to see if the shard was removed due to being down; restore the node to re-add it.

Example fix

// before — shard name does not match config
ring := redis.NewRing(&redis.RingOptions{
    Addrs: map[string]string{"shard1": "host1:6379"},
})
// lookup targets "shard2" which doesn't exist

// after — use the correct shard name
ring := redis.NewRing(&redis.RingOptions{
    Addrs: map[string]string{
        "shard1": "host1:6379",
        "shard2": "host2:6379",
    },
})

func validShardName(name string, addrs map[string]string) error {
    if _, ok := addrs[name]; !ok {
        return fmt.Errorf("shard %q not in RingOptions.Addrs; valid: %v", name, maps.Keys(addrs))
    }
    return nil
}

shard, err := ringSharding.GetByName(name)
if err != nil && err.Error() == "redis: the shard is not in the ring" {
    // shard removed/renamed; retry against current ring or alert
}

When it happens

Trigger: Calling a Ring API that targets a named shard that no longer exists (removed dynamically, or the name was never added). A rebalance removed a downed shard from the ring's active set. Passing a shard name that doesn't match the keys in RingOptions.Addrs.

Common situations: Shard reconfiguration while operations are in flight. A shard name typo or mismatch between config keys and runtime lookups. A shard that was health-voted down and pruned from the consistent-hash ring.

Related errors

• redis: all ring shards are down
• redis: AutoPipelineOptions.NumShards=%d must be >= 0
• redis: Watch requires all keys to be in the same shard
• redis: NewRing nil options
• redis: connection pool exhausted

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