redis/redis-py · error · RedisClusterException

REPLICAOF is not supported in cluster mode

Error message

REPLICAOF is not supported in cluster mode

What it means

Raised by ClusterManagementCommands.replicaof() in redis/commands/cluster.py:466. REPLICAOF is the modern name for SLAVEOF; in cluster mode replication topology is cluster-managed, so the command is explicitly rejected to prevent corrupting the cluster.

Solutions

1. Use CLUSTER REPLICATE / CLUSTER FAILOVER for cluster replication changes.
2. Guard the call so replicaof() is only invoked on standalone clients.
3. Operate on the node's config via redis-cli out of band if you truly need standalone behavior.

Example fix

// before
rc.replicaof('newmaster', 6379)
// after
rc.cluster_replicate(target_node, master_node_id)

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

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

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

When it happens

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

Common situations: Generic replication-management code applied to a cluster client; scripts that re-point replicas during failover without using cluster commands.

Related errors

• SLAVEOF is not supported in cluster mode
• SWAPDB 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
• Cannot issue a WATCH after a MULTI

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

Appendix: source

Thrown at redis/commands/cluster.py:466

    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
    def cluster_myid(
        self: SyncClientProtocol, target_node: "TargetNodesT"
    ) -> bytes | str: ...

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

View on GitHub (pinned to 6a6b581b48)