redis/redis-py · error · NotImplementedError

CLUSTER BUMPEPOCH is intentionally not implemented in the…

Error message

CLUSTER BUMPEPOCH is intentionally not implemented in the client.

What it means

RedisCluster.cluster_bumpepoch() is a stub that always raises NotImplementedError. CLUSTER BUMPEPOCH is a low-level cluster internals command; the client deliberately omits it because epoch bumps are driven by the cluster's own failover/replication protocol and should not be triggered by application code.

Solutions

  1. Do not call cluster_bumpepoch() from this client.
  2. Run `CLUSTER BUMPEPOCH` via redis-cli directly on the target node if you have a confirmed need.
  3. For epoch/failover problems, investigate cluster state with cluster_info()/cluster_nodes() instead of forcing epoch changes.

Example fix

# before
client.cluster_bumpepoch()
# after - use redis-cli on the node if truly required
# redis-cli -h <node> -p <port> CLUSTER BUMPEPOCH
Defensive patterns

Strategy: type-guard

Validate before calling

def safe_cluster_bumpepoch(client):
    if type(client).__name__ in ('RedisCluster', 'AsyncRedisCluster'):
        raise NotImplementedError('cluster_bumpepoch is not supported on the cluster client')
    return client.cluster_bumpepoch()

Type guard

from redis.cluster import RedisCluster
from redis.asyncio.cluster import RedisCluster as AsyncRedisCluster

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

Try / catch

try:
    client.cluster_bumpepoch()
except NotImplementedError:
    # use redis-cli directly on the node if truly required
    pass

Prevention

When it happens

Trigger: Calling client.cluster_bumpepoch() on a RedisCluster or redis.asyncio.RedisCluster instance with any arguments. Raises unconditionally regardless of target_nodes.

Common situations: Exploratory scripting against cluster internals; copying a redis-cli recipe into Python; trying to force epoch advancement during manual cluster repair.

Related errors

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

Appendix: source

Thrown at redis/commands/cluster.py:1026

    ) -> ClusterLinksResponse | Awaitable[ClusterLinksResponse]:
        """
        Each node in a Redis Cluster maintains a pair of long-lived TCP link with each
        peer in the cluster: One for sending outbound messages towards the peer and one
        for receiving inbound messages from the peer.

        This command outputs information of all such peer links as an array.

        For more information see https://redis.io/commands/cluster-links
        """
        return self.execute_command("CLUSTER LINKS", target_nodes=target_node)

    def cluster_flushslots(self, target_nodes: "TargetNodesT" | None = None) -> None:
        raise NotImplementedError(
            "CLUSTER FLUSHSLOTS is intentionally not implemented in the client."
        )

    def cluster_bumpepoch(self, target_nodes: "TargetNodesT" | None = None) -> None:
        raise NotImplementedError(
            "CLUSTER BUMPEPOCH is intentionally not implemented in the client."
        )

    def readonly(self, target_nodes: "TargetNodesT" | None = None) -> ResponseT:
        """
        Enables read queries.
        The command will be sent to the default cluster node if target_nodes is
        not specified.

        For more information see https://redis.io/commands/readonly
        """
        if target_nodes == "replicas" or target_nodes == "all":
            # read_from_replicas will only be enabled if the READONLY command
            # is sent to all replicas
            self.read_from_replicas = True
        return self.execute_command("READONLY", target_nodes=target_nodes)

    def readwrite(self, target_nodes: "TargetNodesT" | None = None) -> ResponseT:

View on GitHub (pinned to 6a6b581b48)