redis/redis-py · error · RedisClusterException

SWAPDB is not supported in cluster mode

Error message

SWAPDB is not supported in cluster mode

What it means

Raised by ClusterManagementCommands.swapdb() in redis/commands/cluster.py:474. SWAPDB swaps two logical databases on a single Redis instance, but Redis Cluster only permits database 0; swapping databases would break the slot-to-node mapping. The method is overridden to fail fast.

Solutions

1. Do not use multiple databases in cluster mode; keep all data in DB 0.
2. If you need logical separation, use key prefixes or hash tags instead of DB indexes.
3. Only call swapdb() on a standalone redis.Redis client.

Example fix

// before
rc.swapdb(0, 1)
// after
# cluster mode supports only db 0; use key namespacing instead
rc.set('featureA:k', 'v')
rc.set('featureB:k', 'v')

from redis.cluster import RedisCluster
if not isinstance(rc, RedisCluster):
    rc.swapdb(0, 1)
# else: cluster supports only db 0; do nothing or use key namespacing

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:
    pass  # cluster mode forbids SWAPDB

When it happens

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

Common situations: Multi-DB application code reused against a cluster endpoint; tooling that reorganizes databases generically.

Related errors

• REPLICAOF is not supported in cluster mode
• SLAVEOF is not supported in cluster mode
• A ``db`` querystring option can only be 0 in cluster mode
• Argument 'db' is not possible to use in cluster mode
• Argument 'db' must be 0 or None in cluster mode

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

Appendix: 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 6a6b581b48)