What causes "{command} - all keys must map to the same key slot" in redis/redis-py?

Use Redis hash tags to force keys into the same slot, e.g. client.mset({'{user1}:name': 'a', '{user1}:email': 'b'}).

redis/redis-py · error · RedisClusterException

- all keys must map to the same key slot

Error message

{command} - all keys must map to the same key slot

What it means

Raised as a RedisClusterException by determine_slot() when a multi-key command has keys that hash to more than one distinct slot. Redis Cluster requires all keys in a single command (MSET, MGET, RENAME, SUNIONSTORE, etc.) to reside in the same hash slot so the command can be routed to a single node. The guard at cluster.py:1492-1496 computes the slot for each key and rejects cross-slot key sets.

Solutions

Use Redis hash tags to force keys into the same slot, e.g. client.mset({'{user1}:name': 'a', '{user1}:email': 'b'}).
Split the multi-key operation into individual per-key commands so each is routed independently.
Use pipeline to batch per-key commands without cross-slot constraints.

Example fix

// before
client.mset({'k1': 'v1', 'k2': 'v2'})

// after (hash tag forces same slot)
client.mset({'{tag}:k1': 'v1', '{tag}:k2': 'v2'})

Defensive patterns

Strategy: validation

Validate before calling

# Validate all keys share a slot before multi-key ops
from redis.cluster import key_slot
def same_slot(keys):
    slots = {key_slot(k.encode()) for k in keys}
    return len(slots) == 1

if not same_slot(['k1', 'k2']):
    raise ValueError('Keys must share a hash slot; use hash tags like {tag}:k1')

Type guard

def keys_in_same_slot(keys: list) -> bool:
    from redis.cluster import key_slot
    return len({key_slot(k.encode() if isinstance(k, str) else k) for k in keys}) == 1

Try / catch

from redis.exceptions import RedisClusterException
try:
    client.mset({'k1': 'v1', 'k2': 'v2'})
except RedisClusterException as e:
    if 'same key slot' in str(e):
        # use hash tags or split into individual ops
        for k, v in {'k1': 'v1', 'k2': 'v2'}.items():
            client.set(k, v)

Prevention

Use hash tags ({tag}) to group related keys in the same slot.
Validate multi-key commands with a same-slot check before sending.
Split cross-slot multi-key operations into individual per-key commands.

When it happens

Trigger: Calling client.mset({'k1': 'v1', 'k2': 'v2'}) where k1 and k2 hash to different slots, or client.rename('src', 'dst') where src and dst are in different slots, or any multi-key operation without hash-tag coordination.

Common situations: Developer assumes multi-key commands work like standalone Redis, or forgets to use hash tags to force keys into the same slot.

Related errors

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

Appendix: source

Thrown at redis/cluster.py:1494

                # FCALL can call a function with 0 keys, that means the function
                #  can be run on any node so we can just return a random slot
                if command.upper() in ("FCALL", "FCALL_RO"):
                    return random.randrange(0, REDIS_CLUSTER_HASH_SLOTS)
                raise RedisClusterException(
                    "No way to dispatch this command to Redis Cluster. "
                    "Missing key.\nYou can execute the command by specifying "
                    f"target nodes.\nCommand: {args}"
                )

        # single key command
        if len(keys) == 1:
            return self.keyslot(keys[0])

        # multi-key command; we need to make sure all keys are mapped to
        # the same slot
        slots = {self.keyslot(key) for key in keys}
        if len(slots) != 1:
            raise RedisClusterException(
                f"{command} - all keys must map to the same key slot"
            )

        return slots.pop()

    def get_encoder(self):
        """
        Get the connections' encoder
        """
        return self.encoder

    def get_connection_kwargs(self):
        """
        Get the connections' key-word arguments
        """
        return self.nodes_manager.connection_kwargs

    def _is_nodes_flag(self, target_nodes):

View on GitHub (pinned to 6a6b581b48)