redis/redis-py · error · RedisClusterException

SLAVEOF is not supported in cluster mode

Error message

SLAVEOF is not supported in cluster mode

What it means

Raised by ClusterManagementCommands.slaveof() in redis/commands/cluster.py:458. SLAVEOF changes a node's replication master, but in Redis Cluster every node's slot ownership and replication topology are managed by the cluster, so the command is forbidden. The method is overridden purely to fail fast with a clear message instead of sending an invalid command.

Solutions

  1. Use CLUSTER subcommands (CLUSTER FAILOVER, CLUSTER REPLICATE) to manage cluster replication.
  2. Branch on client type: only call slaveof() on a standalone redis.Redis client.
  3. Prefer replicaof()/cluster_replicate() for newer Redis deployments.

Example fix

// before
rc.slaveof('newmaster', 6379)
// after
rc.cluster_replicate(target_node, master_node_id)
Defensive patterns

Strategy: type-guard

Validate before calling

from redis.cluster import RedisCluster
if not isinstance(rc, RedisCluster):
    rc.slaveof(host, port)
else:
    rc.cluster_replicate(target_node, master_node_id)

Type guard

from redis.cluster import RedisCluster
def is_cluster_client(client) -> bool:
    return isinstance(client, RedisCluster)

Try / catch

from redis.exceptions import RedisClusterException
try:
    rc.slaveof(host, port)
except RedisClusterException:
    rc.cluster_replicate(target_node, master_node_id)

Prevention

When it happens

Trigger: Calling rc.slaveof(...) on a RedisCluster client instance.

Common situations: Code shared between standalone and cluster deployments that unconditionally calls slaveof(); automation that reconfigures replication generically.

Related errors

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

Appendix: source

Thrown at redis/commands/cluster.py:458

        ]
        return await pipe.execute()


class ClusterManagementCommands(ManagementCommands):
    """
    A class for Redis Cluster management commands

    The class inherits from Redis's core ManagementCommands class and do the
    required adjustments to work with cluster mode
    """

    def slaveof(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/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

View on GitHub (pinned to 6a6b581b48)