redis/redis-py · error · NotImplementedError

HOTKEYS commands are not supported in cluster mode. Please u

Error message

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

What it means

hotkeys_start() on the sync ClusterManagementCommands mixin always raises NotImplementedError. The HOTKEYS feature (sampling frequent keys) is a per-node facility that the cluster client deliberately does not support because hot-keys semantics across a sharded cluster are ambiguous; you must use the non-cluster Redis client against a single node.

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

Solutions

1. Instantiate a standalone redis.Redis connected to one node (e.g. redis.Redis(host=node.host, port=node.port)) and call hotkeys_start on that.
2. If you need cluster-wide hot keys, run hotkeys_start per node via standalone clients and aggregate client-side.
3. Remove the cluster client from the call path for this command.

Example fix

# before
cluster_r = redis.cluster.RedisCluster(...)
cluster_r.hotkeys_start(['accessed'], count=10)
# after
import redis
node_r = redis.Redis(host='127.0.0.1', port=7000)
node_r.hotkeys_start(['accessed'], count=10)

import redis
# Use a standalone client for hotkeys instead of the cluster client.
if isinstance(client, redis.cluster.RedisCluster):
    raise TypeError('hotkeys_start requires a non-cluster redis.Redis client')

import redis
def is_standalone_client(client) -> bool:
    return isinstance(client, redis.Redis) and not isinstance(client, redis.cluster.RedisCluster)

try:
    client.hotkeys_start(metrics, count=count)
except NotImplementedError:
    node_client = redis.Redis(host=node.host, port=node.port)
    node_client.hotkeys_start(metrics, count=count)

When it happens

Trigger: Calling r.hotkeys_start(metrics, count=..., duration=..., sample_ratio=..., slots=...) on a redis.cluster.RedisCluster instance (sync). The body at redis/commands/cluster.py:1140 raises regardless of arguments.

Common situations: Profiling key access frequency in a deployment that happens to be clustered; copy-paste from a standalone-Redis observability playbook; assuming the method exists because the standalone client has it.

Related errors

• CLUSTER FLUSHSLOTS is intentionally not implemented in the c
• CLUSTER BUMPEPOCH is intentionally not implemented in the cl
• PubSub is not supported for RedisCluster
• {cmd_name.upper()} command doesn't exist in Redis commands
• Subcommand {subcommand_name} not found in command {command_n

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/f41070936ad079d0.json. Report an issue: GitHub.