redis/redis-py · error · RedisClusterException

REPLICAOF is not supported in cluster mode

Error message

REPLICAOF is not supported in cluster mode

What it means

RedisClusterCommands.replicaof (redis/commands/cluster.py:460) unconditionally raises. REPLICAOF is the non-deprecated successor to SLAVEOF for standalone redis; in cluster mode a node's replica role is governed by the cluster slot/replication config, so the command is not exposed on the cluster client.

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 da03cdc7e8)

Solutions

1. Use CLUSTER FAILOVER for controlled replica-to-primary promotion: rc.cluster_failover(target_node=replica, option='FORCE').
2. Manage replication links through cluster admin tooling (redis-cli --cluster) rather than REPLICAOF.
3. If you must run REPLICAOF on one specific node, connect a non-cluster client to that single node.

Example fix

# before
rc.replicaof('newmaster', 6379)  # raises

# after
rc.cluster_failover(target_node=replica_node, option='TAKEOVER')

from redis.cluster import RedisCluster

def safe_replicaof(client, host=None, port=None):
    if isinstance(client, RedisCluster):
        raise ValueError('REPLICAOF is unsupported in cluster mode; use cluster_failover()')
    return client.replicaof(host, port)

from redis.cluster import RedisCluster

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

from redis.exceptions import RedisClusterException

try:
    rc.replicaof('NO', 'ONE')
except RedisClusterException:
    rc.cluster_failover(target_node=replica, option='FORCE')

When it happens

Trigger: Calling rc.replicaof(...) (including rc.replicaof('NO','ONE')) on a RedisCluster client.

Common situations: Failover/demotion tooling written for standalone redis being pointed at a cluster. Scripts that call REPLICAOF NO ONE to promote a node during an incident. Renaming SLAVEOF to REPLICAOF in legacy code without changing the client type.

Related errors

• SLAVEOF is not supported in cluster mode
• SWAPDB 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/49e403cc436d7f37.json. Report an issue: GitHub.