go-redis/redis · critical

redis: all ring shards are down

Error message

redis: all ring shards are down

What it means

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.

Source

Thrown at ring.go:22

	"context"
	"crypto/tls"
	"errors"
	"fmt"
	"math/rand"
	"net"
	"strconv"
	"sync"
	"sync/atomic"
	"time"

	"github.com/redis/go-redis/v9/auth"
	"github.com/redis/go-redis/v9/internal"
	"github.com/redis/go-redis/v9/internal/hashtag"
	"github.com/redis/go-redis/v9/internal/pool"
	"github.com/redis/go-redis/v9/internal/proto"
)

var errRingShardsDown = errors.New("redis: all ring shards are down")

// defaultHeartbeatFn is the default function used to check the shard liveness
var defaultHeartbeatFn = func(ctx context.Context, client *Client) bool {
	err := client.Ping(ctx).Err()
	return err == nil || err == pool.ErrPoolTimeout
}

//------------------------------------------------------------------------------

type ConsistentHash interface {
	Get(string) string
}

func newRendezvous(shards []string) ConsistentHash {
	return hashtag.NewRendezvousHash(shards)
}

//------------------------------------------------------------------------------

View on GitHub (pinned to 36d97525cd)

Solutions

1. Verify each shard address in the Ring config is reachable: telnet/redis-cli ping each host:port.
2. Check network connectivity, DNS resolution, and firewall rules from the application host to every Redis node.
3. If using TLS or auth, confirm credentials/cert paths are correct for all shards.
4. Inspect logs for dial errors and raise RingOptions.MaxRetries / HeartbeatInterval if nodes recover slowly.

Example fix

// before
ring := redis.NewRing(&redis.RingOptions{
    Addrs: map[string]string{"shard1": "bad-host:6379"}, // unreachable
})
// ring.Get(ctx, "k").Err() => redis: all ring shards are down

// after — corrected, reachable addresses + retries
ring := redis.NewRing(&redis.RingOptions{
    Addrs: map[string]string{
        "shard1": "redis-1.internal:6379",
        "shard2": "redis-2.internal:6379",
    },
    MaxRetries: 5,
})

func ringHasShards(opt *redis.RingOptions) error {
    if len(opt.Addrs) == 0 {
        return errors.New("RingOptions.Addrs is empty; configure at least one reachable shard")
    }
    return nil
}

_, err := ring.Get(ctx, key).Result()
if err != nil && err.Error() == "redis: all ring shards are down" {
    // all shards unreachable; trigger circuit breaker / fallback / alerting
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• redis: all sentinels specified in configuration are unreacha
• redis: the shard is not in the ring
• redis: all sentinels specified in configuration are unreacha
• redis: NewRing nil options
• redis: connection pool exhausted

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