{"id":"3c99b168e173c3d7","repo":"redis/redis-py","slug":"shard-hint-is-deprecated-in-cluster-mode","errorCode":null,"errorMessage":"shard_hint is deprecated in cluster mode","messagePattern":"shard_hint is deprecated in cluster mode","errorType":"exception","errorClass":"RedisClusterException","httpStatus":null,"severity":"error","filePath":"redis/asyncio/cluster.py","lineNumber":1456,"sourceCode":"            command_name=command,\n            duration_seconds=time.monotonic() - start_time,\n            connection=target_node,\n            error=e,\n        )\n        raise e\n\n    def pipeline(\n        self, transaction: Optional[Any] = None, shard_hint: Optional[Any] = None\n    ) -> \"ClusterPipeline\":\n        \"\"\"\n        Create & return a new :class:`~.ClusterPipeline` object.\n\n        Cluster implementation of pipeline does not support transaction or shard_hint.\n\n        :raises RedisClusterException: if transaction or shard_hint are truthy values\n        \"\"\"\n        if shard_hint:\n            raise RedisClusterException(\"shard_hint is deprecated in cluster mode\")\n\n        return ClusterPipeline(self, transaction)\n\n    def pubsub(\n        self,\n        node: Optional[\"ClusterNode\"] = None,\n        host: Optional[str] = None,\n        port: Optional[int] = None,\n        **kwargs: Any,\n    ) -> \"ClusterPubSub\":\n        \"\"\"\n        Create and return a ClusterPubSub instance.\n\n        Allows passing a ClusterNode, or host&port, to get a pubsub instance\n        connected to the specified node\n\n        :param node: ClusterNode to connect to\n        :param host: Host of the node to connect to","sourceCodeStart":1438,"sourceCodeEnd":1474,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/asyncio/cluster.py#L1438-L1474","documentation":"Raised by RedisCluster.pipeline() when shard_hint is passed as a truthy value. shard_hint is a connection-pool concept from the standalone Redis client used to route connections to a specific shard; it has no meaning in cluster mode where routing is automatic by hash slot. The cluster pipeline explicitly rejects it to prevent silent misconfiguration.","triggerScenarios":"Calling rc.pipeline(transaction=True, shard_hint='somehint') or porting standalone code rc.pipeline(shard_hint=...) to a RedisCluster client. Any truthy (non-None, non-empty) value triggers it at cluster.py:1455.","commonSituations":"Copy-pasting pipeline() kwargs from a standalone Redis() client into a RedisCluster() client; legacy codebases that used shard_hint with redis-py's old cluster sharding helpers.","solutions":["Drop the shard_hint argument entirely: rc.pipeline().","If you need to target a specific shard, instead pass target_nodes on the individual pipeline commands or use the per-node connection pool directly.","Set shard_hint=None (the default) explicitly to make the intent clear during migration."],"exampleFix":"// before\npipe = rc.pipeline(transaction=True, shard_hint='users')\n\n// after\npipe = rc.pipeline(transaction=True)","handlingStrategy":"validation","validationCode":"def cluster_pipeline(rc, transaction=None, shard_hint=None):\n    if shard_hint:\n        raise ValueError('shard_hint is not supported by RedisCluster.pipeline()')\n    return rc.pipeline(transaction=transaction)","typeGuard":"from typing import Any\n\ndef is_clean_pipeline_kwargs(transaction=None, shard_hint=None) -> bool:\n    return not shard_hint","tryCatchPattern":"try:\n    pipe = rc.pipeline(transaction=True, shard_hint=hint)\nexcept Exception as e:\n    if 'shard_hint' in str(e):\n        pipe = rc.pipeline(transaction=True)\n    else:\n        raise","preventionTips":["Never copy pipeline() kwargs from a standalone Redis() client into RedisCluster().","If migrating, explicitly set shard_hint=None and remove the argument once confirmed.","Lint for shard_hint= usages against cluster clients in code review."],"tags":["redis-cluster","pipeline","shard-hint","deprecated"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}