redis/redis-py · error · RedisClusterException

SWAPDB is not supported in cluster mode

Error message

SWAPDB is not supported in cluster mode

What it means

RedisClusterCommands.swapdb (redis/commands/cluster.py:468) unconditionally raises. SWAPDB swaps two logical databases on a single standalone Redis instance; Redis Cluster only uses database 0 (slots are not multi-database), so swapping databases is meaningless in cluster mode and the command is disabled.

Source

Thrown at redis/commands/cluster.py:474

        For more information see https://redis.io/commands/slaveof
        """
        raise RedisClusterException("SLAVEOF is not supported in cluster mode")

    def replicaof(self, *args, **kwargs) -> NoReturn:
        """
        Make the server a replica of another instance, or promote it as master.

        For more information see https://redis.io/commands/replicaof
        """
        raise RedisClusterException("REPLICAOF is not supported in cluster mode")

    def swapdb(self, *args, **kwargs) -> NoReturn:
        """
        Swaps two Redis databases.

        For more information see https://redis.io/commands/swapdb
        """
        raise RedisClusterException("SWAPDB is not supported in cluster mode")

    @overload
    def cluster_myid(
        self: SyncClientProtocol, target_node: "TargetNodesT"
    ) -> bytes | str: ...

    @overload
    def cluster_myid(
        self: AsyncClientProtocol, target_node: "TargetNodesT"
    ) -> Awaitable[bytes | str]: ...

    def cluster_myid(self, target_node: "TargetNodesT") -> (bytes | str) | Awaitable[
        bytes | str
    ]:
        """
        Returns the node's id.

        :target_node: 'ClusterNode'

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Stop using multiple databases; cluster mode requires DB 0. Move data into separate key namespaces (prefixes or hash tags) instead of DB indexes.
2. If you genuinely need SWAPDB, connect a non-cluster client to a single standalone node that is not in cluster mode.
3. Redesign the data layout to use key namespacing (e.g. 'svcA:k', 'svcB:k') rather than DB numbers.

Example fix

# before
rc.swapdb(0, 1)  # raises: SWAPDB is not supported in cluster mode

# after
# use key namespacing instead of DBs in cluster mode
rc.set('svcA:user', 'alice')
rc.set('svcB:user', 'bob')

from redis.cluster import RedisCluster

def safe_swapdb(client, i, j):
    if isinstance(client, RedisCluster):
        raise ValueError('SWAPDB is unsupported in cluster mode; cluster uses DB 0 only')
    return client.swapdb(i, j)

from redis.cluster import RedisCluster

def is_cluster_client(client) -> bool:
    return isinstance(client, RedisCluster)

from redis.exceptions import RedisClusterException

try:
    rc.swapdb(0, 1)
except RedisClusterException:
    # cluster has only DB 0; redesign to use key namespacing instead
    ...

When it happens

Trigger: Calling rc.swapdb(0, 1) on a RedisCluster client.

Common situations: Code that uses multiple logical databases on standalone redis and is pointed at a cluster. Migration tooling that swaps DBs during deployment. Misunderstanding that cluster mode implies DB 0 only.

Related errors

• SLAVEOF is not supported in cluster mode
• REPLICAOF is not supported in cluster mode
• {cmd_name.upper()} command doesn't exist in Redis commands
• Subcommand {subcommand_name} not found in command {command_n
• Command {command_name} not found in commands

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/178480cc78b56df9.json. Report an issue: GitHub.