redis/redis-py · error · SlotNotCoveredError

Slot " " is not covered by the cluster.

Error message

Slot "{slot}" is not covered by the cluster.

What it means

Raised as a SlotNotCoveredError by get_node_from_key() when the computed hash slot for the given key has no entry in the cluster's slots_cache. This means the client's local view of the cluster topology has no node assigned to that slot, typically because topology discovery has not run, slots moved, or the cluster is degraded. SlotNotCoveredError is a subclass of RedisClusterException whose docstring instructs the client to drop the node layout and reconnect/refresh.

Solutions

  1. Trigger a topology refresh by catching the error and calling client.cluster_reload_slots() or reinitializing the client.
  2. Retry the operation after a short backoff to allow the cluster to complete failover/resharding.
  3. Ensure the cluster has full slot coverage (CLUSTER NODES / CLUSTER SLOTS) and all primaries are healthy.
  4. If persistent, set require_full_coverage appropriately and verify no nodes are in FAIL or PFAIL state.

Example fix

// before
node = client.get_node_from_key('mykey')

// after
from redis.exceptions import SlotNotCoveredError
try:
    node = client.get_node_from_key('mykey')
except SlotNotCoveredError:
    client.cluster_reload_slots()
    node = client.get_node_from_key('mykey')
Defensive patterns

Strategy: retry

Validate before calling

from redis.cluster import key_slot
slot = key_slot(b'mykey') % 16384
node = client.nodes_manager.slots_cache.get(slot)
if not node:
    client.cluster_reload_slots()  # refresh before proceeding

Type guard

def is_slot_covered(client, key: str) -> bool:
    slot = client.keyslot(key)
    cache = client.nodes_manager.slots_cache.get(slot)
    return cache is not None and len(cache) > 0

Try / catch

from redis.exceptions import SlotNotCoveredError
try:
    node = client.get_node_from_key(key)
except SlotNotCoveredError:
    client.cluster_reload_slots()
    node = client.get_node_from_key(key)

Prevention

When it happens

Trigger: Calling client.get_node_from_key(key) or any code path that resolves a key to a node (e.g., shard-channel operations) when the key's slot is absent from nodes_manager.slots_cache. The check at cluster.py:1069-1071 fires when slot_cache is None or empty.

Common situations: Cluster is mid-failover or resharding, a slot was moved to a node the client hasn't discovered yet, the initial topology refresh failed to populate all slots, or the cluster is in a degraded state with unassigned slots.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/4e75bb81868c5a48. Report an issue: GitHub.

Appendix: source

Thrown at redis/cluster.py:1071

        """
        if self.read_from_replicas and command_name in READ_COMMANDS:
            return self.get_random_node()

        return self.get_random_primary_node()

    def get_nodes(self):
        return list(self.nodes_manager.nodes_cache.values())

    def get_node_from_key(self, key, replica=False):
        """
        Get the node that holds the key's slot.
        If replica set to True but the slot doesn't have any replicas, None is
        returned.
        """
        slot = self.keyslot(key)
        slot_cache = self.nodes_manager.slots_cache.get(slot)
        if slot_cache is None or len(slot_cache) == 0:
            raise SlotNotCoveredError(f'Slot "{slot}" is not covered by the cluster.')
        if replica and len(self.nodes_manager.slots_cache[slot]) < 2:
            return None
        elif replica:
            node_idx = 1
        else:
            # primary
            node_idx = 0

        return slot_cache[node_idx]

    def get_default_node(self):
        """
        Get the cluster's default node
        """
        return self.nodes_manager.default_node

    def get_nodes_from_slot(self, command: str, *args):
        """

View on GitHub (pinned to 6a6b581b48)