{"id":"d0be7703a42b25f3","repo":"go-redis/redis","slug":"redis-all-ring-shards-are-down","errorCode":null,"errorMessage":"redis: all ring shards are down","messagePattern":"redis: all ring shards are down","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"ring.go","lineNumber":22,"sourceCode":"\t\"context\"\n\t\"crypto/tls\"\n\t\"errors\"\n\t\"fmt\"\n\t\"math/rand\"\n\t\"net\"\n\t\"strconv\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"time\"\n\n\t\"github.com/redis/go-redis/v9/auth\"\n\t\"github.com/redis/go-redis/v9/internal\"\n\t\"github.com/redis/go-redis/v9/internal/hashtag\"\n\t\"github.com/redis/go-redis/v9/internal/pool\"\n\t\"github.com/redis/go-redis/v9/internal/proto\"\n)\n\nvar errRingShardsDown = errors.New(\"redis: all ring shards are down\")\n\n// defaultHeartbeatFn is the default function used to check the shard liveness\nvar defaultHeartbeatFn = func(ctx context.Context, client *Client) bool {\n\terr := client.Ping(ctx).Err()\n\treturn err == nil || err == pool.ErrPoolTimeout\n}\n\n//------------------------------------------------------------------------------\n\ntype ConsistentHash interface {\n\tGet(string) string\n}\n\nfunc newRendezvous(shards []string) ConsistentHash {\n\treturn hashtag.NewRendezvousHash(shards)\n}\n\n//------------------------------------------------------------------------------","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/go-redis/redis/blob/36d97525cd8076aed67cddf54778e9ea84550929/ring.go#L4-L40","documentation":"errRingShardsDown is returned by Ring operations when no shard in the ring is reachable (all have been voted down by the heartbeat, or the ring has zero shards). The Ring's GetByKey/Random return this when c.numShard == 0 or consistent hashing returns no shard name. It indicates a total outage of every configured Redis node.","triggerScenarios":"All Redis servers backing the Ring are unreachable (network partition, all nodes down, wrong host/port). The Ring was constructed with no valid shard addresses. Heartbeat health checks voted every shard down and none recovered within the retry window.","commonSituations":"Network outage or firewall blocking all Redis endpoints. Misconfigured Ring addresses (wrong ports, DNS failures). All nodes restarted and the heartbeat hasn't re-established connections. TLS/auth misconfiguration causing every dial to fail.","solutions":["Verify each shard address in the Ring config is reachable: telnet/redis-cli ping each host:port.","Check network connectivity, DNS resolution, and firewall rules from the application host to every Redis node.","If using TLS or auth, confirm credentials/cert paths are correct for all shards.","Inspect logs for dial errors and raise RingOptions.MaxRetries / HeartbeatInterval if nodes recover slowly."],"exampleFix":"// before\nring := redis.NewRing(&redis.RingOptions{\n    Addrs: map[string]string{\"shard1\": \"bad-host:6379\"}, // unreachable\n})\n// ring.Get(ctx, \"k\").Err() => redis: all ring shards are down\n\n// after — corrected, reachable addresses + retries\nring := redis.NewRing(&redis.RingOptions{\n    Addrs: map[string]string{\n        \"shard1\": \"redis-1.internal:6379\",\n        \"shard2\": \"redis-2.internal:6379\",\n    },\n    MaxRetries: 5,\n})","handlingStrategy":"retry","validationCode":"func ringHasShards(opt *redis.RingOptions) error {\n    if len(opt.Addrs) == 0 {\n        return errors.New(\"RingOptions.Addrs is empty; configure at least one reachable shard\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"_, err := ring.Get(ctx, key).Result()\nif err != nil && err.Error() == \"redis: all ring shards are down\" {\n    // all shards unreachable; trigger circuit breaker / fallback / alerting\n}","preventionTips":["Health-check each shard address at startup (PING) before serving traffic.","Configure multiple shards across independent hosts for redundancy.","Monitor shard heartbeat state and alert before all go down.","Set MaxRetries and HeartbeatInterval to tolerate transient outages."],"tags":["ring","network","outage","availability","configuration"],"analyzedSha":"36d97525cd8076aed67cddf54778e9ea84550929","analyzedAt":"2026-08-06T01:08:27.376Z","schemaVersion":2}