{"id":"f42d922727e1acca","repo":"go-redis/redis","slug":"redis-the-shard-is-not-in-the-ring","errorCode":null,"errorMessage":"redis: the shard is not in the ring","messagePattern":"redis: the shard is not in the ring","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"ring.go","lineNumber":505,"sourceCode":"\n\tshardName := c.hash.Get(key)\n\tif shardName == \"\" {\n\t\treturn nil, errRingShardsDown\n\t}\n\treturn c.shards.m[shardName], nil\n}\n\nfunc (c *ringSharding) GetByName(shardName string) (*ringShard, error) {\n\tif shardName == \"\" {\n\t\treturn c.Random()\n\t}\n\n\tc.mu.RLock()\n\tdefer c.mu.RUnlock()\n\n\tshard, ok := c.shards.m[shardName]\n\tif !ok {\n\t\treturn nil, errors.New(\"redis: the shard is not in the ring\")\n\t}\n\n\treturn shard, nil\n}\n\nfunc (c *ringSharding) Random() (*ringShard, error) {\n\treturn c.GetByKey(strconv.Itoa(rand.Int()))\n}\n\n// Heartbeat monitors state of each shard in the ring.\nfunc (c *ringSharding) Heartbeat(ctx context.Context, frequency time.Duration) {\n\tticker := time.NewTicker(frequency)\n\tdefer ticker.Stop()\n\n\tfor {\n\t\tselect {\n\t\tcase <-ticker.C:\n\t\t\tvar rebalance bool","sourceCodeStart":487,"sourceCodeEnd":523,"githubUrl":"https://github.com/go-redis/redis/blob/36d97525cd8076aed67cddf54778e9ea84550929/ring.go#L487-L523","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the shard name matches a key in RingOptions.Addrs exactly.","If shards are reconfigured at runtime, ensure in-flight operations complete or retry against the updated ring.","Check heartbeat/rebalance logs to see if the shard was removed due to being down; restore the node to re-add it."],"exampleFix":"// before — shard name does not match config\nring := redis.NewRing(&redis.RingOptions{\n    Addrs: map[string]string{\"shard1\": \"host1:6379\"},\n})\n// lookup targets \"shard2\" which doesn't exist\n\n// after — use the correct shard name\nring := redis.NewRing(&redis.RingOptions{\n    Addrs: map[string]string{\n        \"shard1\": \"host1:6379\",\n        \"shard2\": \"host2:6379\",\n    },\n})","handlingStrategy":"validation","validationCode":"func validShardName(name string, addrs map[string]string) error {\n    if _, ok := addrs[name]; !ok {\n        return fmt.Errorf(\"shard %q not in RingOptions.Addrs; valid: %v\", name, maps.Keys(addrs))\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"shard, err := ringSharding.GetByName(name)\nif err != nil && err.Error() == \"redis: the shard is not in the ring\" {\n    // shard removed/renamed; retry against current ring or alert\n}","preventionTips":["Keep shard name keys in RingOptions.Addrs stable across reconfigurations.","Drain in-flight operations before removing a shard from the ring.","Cross-check runtime shard-name lookups against the configured Addrs keys."],"tags":["ring","sharding","configuration","rebalance"],"analyzedSha":"36d97525cd8076aed67cddf54778e9ea84550929","analyzedAt":"2026-08-06T01:08:27.376Z","schemaVersion":2}