redis/redis-py · error · NotImplementedError

HOTKEYS commands are not supported in cluster mode. Please…

Error message

HOTKEYS commands are not supported in cluster mode. Please use the non-cluster client.

What it means

RedisCluster.hotkeys_start() (sync) always raises NotImplementedError. The HOTKEYS feature is a per-node sampling facility that does not make sense in a clustered topology where keys are sharded across many nodes, so the cluster client surface deliberately blocks it and tells you to use the non-cluster Redis client connected to a specific node.

Solutions

Use redis.Redis (not RedisCluster) connected to the specific node you want to analyze and call hotkeys_start() there.
If you need hotkeys across the cluster, iterate each node's connection and call hotkeys_start() per node.
Remove the hotkeys call path from code that uses RedisCluster.

Example fix

# before
r = redis.cluster.RedisCluster(...)
r.hotkeys_start(['accesses'], count=100)
# after
node = redis.Redis(host='node-host', port=7000)
node.hotkeys_start(['accesses'], count=100)

Defensive patterns

Strategy: type-guard

Validate before calling

def cluster_aware_hotkeys_start(client, *args, **kwargs):
    from redis.cluster import RedisCluster
    if isinstance(client, RedisCluster):
        raise NotImplementedError('Use redis.Redis per-node for hotkeys_start')
    return client.hotkeys_start(*args, **kwargs)

Type guard

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

Try / catch

try:
    client.hotkeys_start(metrics, count=count)
except NotImplementedError as e:
    if 'HOTKEYS' in str(e):
        node_client = redis.Redis(host=node_host, port=node_port)
        node_client.hotkeys_start(metrics, count=count)

Prevention

Maintain a separate non-cluster client for per-node introspection commands.
Gate hotkeys calls behind a client-type check in your observability layer.
Document which commands are cluster-unsupported for your team.

When it happens

Trigger: Calling client.hotkeys_start(metrics, count=..., duration=..., sample_ratio=..., slots=...) on a redis.cluster.RedisCluster instance. Any call, with any arguments, raises immediately.

Common situations: Running hot-keys analysis against a cluster deployment; reusing a hotkeys script written for standalone Redis against a cluster URL; upgrading from standalone to cluster client and forgetting to swap the hotkeys calls.

Related errors

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

Appendix: source

Thrown at redis/commands/cluster.py:1140

            noloop,
            target_nodes=target_nodes,
        )

    def hotkeys_start(
        self,
        metrics: List[HotkeysMetricsTypes],
        count: int | None = None,
        duration: int | None = None,
        sample_ratio: int | None = None,
        slots: List[int] | None = None,
        **kwargs,
    ) -> str | bytes:
        """
        Cluster client does not support hotkeys command. Please use the non-cluster client.

        For more information see https://redis.io/commands/hotkeys-start
        """
        raise NotImplementedError(
            "HOTKEYS commands are not supported in cluster mode. Please use the non-cluster client."
        )

    def hotkeys_stop(self, **kwargs) -> str | bytes:
        """
        Cluster client does not support hotkeys command. Please use the non-cluster client.

        For more information see https://redis.io/commands/hotkeys-stop
        """
        raise NotImplementedError(
            "HOTKEYS commands are not supported in cluster mode. Please use the non-cluster client."
        )

    def hotkeys_reset(self, **kwargs) -> str | bytes:
        """
        Cluster client does not support hotkeys command. Please use the non-cluster client.

        For more information see https://redis.io/commands/hotkeys-reset

View on GitHub (pinned to 6a6b581b48)