{"id":"f41070936ad079d0","repo":"redis/redis-py","slug":"hotkeys-commands-are-not-supported-in-cluster-mode","errorCode":null,"errorMessage":"HOTKEYS commands are not supported in cluster mode. Please use the non-cluster client.","messagePattern":"HOTKEYS commands are not supported in cluster mode\\. Please use the non-cluster client\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"redis/commands/cluster.py","lineNumber":1140,"sourceCode":"            noloop,\n            target_nodes=target_nodes,\n        )\n\n    def hotkeys_start(\n        self,\n        metrics: List[HotkeysMetricsTypes],\n        count: int | None = None,\n        duration: int | None = None,\n        sample_ratio: int | None = None,\n        slots: List[int] | None = None,\n        **kwargs,\n    ) -> str | bytes:\n        \"\"\"\n        Cluster client does not support hotkeys command. Please use the non-cluster client.\n\n        For more information see https://redis.io/commands/hotkeys-start\n        \"\"\"\n        raise NotImplementedError(\n            \"HOTKEYS commands are not supported in cluster mode. Please use the non-cluster client.\"\n        )\n\n    def hotkeys_stop(self, **kwargs) -> str | bytes:\n        \"\"\"\n        Cluster client does not support hotkeys command. Please use the non-cluster client.\n\n        For more information see https://redis.io/commands/hotkeys-stop\n        \"\"\"\n        raise NotImplementedError(\n            \"HOTKEYS commands are not supported in cluster mode. Please use the non-cluster client.\"\n        )\n\n    def hotkeys_reset(self, **kwargs) -> str | bytes:\n        \"\"\"\n        Cluster client does not support hotkeys command. Please use the non-cluster client.\n\n        For more information see https://redis.io/commands/hotkeys-reset","sourceCodeStart":1122,"sourceCodeEnd":1158,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/commands/cluster.py#L1122-L1158","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If you need cluster-wide hot keys, run hotkeys_start per node via standalone clients and aggregate client-side.","Remove the cluster client from the call path for this command."],"exampleFix":"# before\ncluster_r = redis.cluster.RedisCluster(...)\ncluster_r.hotkeys_start(['accessed'], count=10)\n# after\nimport redis\nnode_r = redis.Redis(host='127.0.0.1', port=7000)\nnode_r.hotkeys_start(['accessed'], count=10)","handlingStrategy":"type-guard","validationCode":"import redis\n# Use a standalone client for hotkeys instead of the cluster client.\nif isinstance(client, redis.cluster.RedisCluster):\n    raise TypeError('hotkeys_start requires a non-cluster redis.Redis client')","typeGuard":"import redis\ndef is_standalone_client(client) -> bool:\n    return isinstance(client, redis.Redis) and not isinstance(client, redis.cluster.RedisCluster)","tryCatchPattern":"try:\n    client.hotkeys_start(metrics, count=count)\nexcept NotImplementedError:\n    node_client = redis.Redis(host=node.host, port=node.port)\n    node_client.hotkeys_start(metrics, count=count)","preventionTips":["Keep a standalone redis.Redis handle per node for hotkeys work.","Do not assume method parity between cluster and standalone surfaces."],"tags":["cluster","unsupported","hotkeys","observability","notimplemented"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}