{"record":{"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":1457,"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":1439,"sourceCodeEnd":1475,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/asyncio/cluster.py#L1439-L1475","documentation":"Raised by RedisCluster.pipeline() when shard_hint is a truthy value. The cluster pipeline does not shard connections by hint (unlike the standalone client), so the argument is rejected outright rather than silently ignored, which would mask a programmer mistake.","triggerScenarios":"Calling rc.pipeline(transaction=True, shard_hint='something') or passing any non-None/non-empty shard_hint to the cluster client's pipeline().","commonSituations":"Copy-pasting standalone-client pipeline code (where shard_hint historically appeared) into cluster code; legacy codebases migrated to RedisCluster without removing the argument.","solutions":["Drop the shard_hint argument entirely when calling the cluster pipeline.","If you need transaction semantics, pass transaction=True only; shard routing is handled automatically by key slot.","Audit codepaths that constructed pipelines generically and forward kwargs; strip shard_hint before calling."],"exampleFix":"// before\npipe = rc.pipeline(transaction=True, shard_hint='users')\n\n// after\npipe = rc.pipeline(transaction=True)","handlingStrategy":"validation","validationCode":"def safe_cluster_pipeline(rc, transaction=None, **kwargs):\n    kwargs.pop('shard_hint', None)  # ignored in cluster mode\n    return rc.pipeline(transaction=transaction, **kwargs)","typeGuard":"null","tryCatchPattern":"from redis.exceptions import RedisClusterException\ntry:\n    pipe = rc.pipeline(transaction=True, shard_hint=hint)\nexcept RedisClusterException as e:\n    if 'shard_hint is deprecated' in str(e):\n        pipe = rc.pipeline(transaction=True)","preventionTips":["Never pass shard_hint to the cluster pipeline.","Strip shard_hint in generic pipeline factory helpers that serve both standalone and cluster clients.","Grep the codebase for 'shard_hint' when migrating to RedisCluster."],"tags":["cluster","pipeline","deprecated","api-usage"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}