{"record":{"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/6a6b581b48225afa0b76912d1028c6035baee932/redis/commands/cluster.py#L1122-L1158","documentation":"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.","triggerScenarios":"Calling client.hotkeys_start(metrics, count=..., duration=..., sample_ratio=..., slots=...) on a redis.cluster.RedisCluster instance. Any call, with any arguments, raises immediately.","commonSituations":"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.","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."],"exampleFix":"# before\nr = redis.cluster.RedisCluster(...)\nr.hotkeys_start(['accesses'], count=100)\n# after\nnode = redis.Redis(host='node-host', port=7000)\nnode.hotkeys_start(['accesses'], count=100)","handlingStrategy":"type-guard","validationCode":"def cluster_aware_hotkeys_start(client, *args, **kwargs):\n    from redis.cluster import RedisCluster\n    if isinstance(client, RedisCluster):\n        raise NotImplementedError('Use redis.Redis per-node for hotkeys_start')\n    return client.hotkeys_start(*args, **kwargs)","typeGuard":"from redis.cluster import RedisCluster\ndef supports_hotkeys(client) -> bool:\n    return not isinstance(client, RedisCluster)","tryCatchPattern":"try:\n    client.hotkeys_start(metrics, count=count)\nexcept NotImplementedError as e:\n    if 'HOTKEYS' in str(e):\n        node_client = redis.Redis(host=node_host, port=node_port)\n        node_client.hotkeys_start(metrics, count=count)","preventionTips":["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."],"tags":["redis-cluster","not-implemented","hotkeys","intentional-stub"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}