redis/redis-py · error · RedisClusterException

shard_hint is deprecated in cluster mode

Error message

shard_hint is deprecated in cluster mode

What it means

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.

Solutions

1. Drop the shard_hint argument entirely when calling the cluster pipeline.
2. If you need transaction semantics, pass transaction=True only; shard routing is handled automatically by key slot.
3. Audit codepaths that constructed pipelines generically and forward kwargs; strip shard_hint before calling.

Example fix

// before
pipe = rc.pipeline(transaction=True, shard_hint='users')

// after
pipe = rc.pipeline(transaction=True)

def safe_cluster_pipeline(rc, transaction=None, **kwargs):
    kwargs.pop('shard_hint', None)  # ignored in cluster mode
    return rc.pipeline(transaction=transaction, **kwargs)

null

from redis.exceptions import RedisClusterException
try:
    pipe = rc.pipeline(transaction=True, shard_hint=hint)
except RedisClusterException as e:
    if 'shard_hint is deprecated' in str(e):
        pipe = rc.pipeline(transaction=True)

When it happens

Trigger: Calling rc.pipeline(transaction=True, shard_hint='something') or passing any non-None/non-empty shard_hint to the cluster client's pipeline().

Common situations: Copy-pasting standalone-client pipeline code (where shard_hint historically appeared) into cluster code; legacy codebases migrated to RedisCluster without removing the argument.

Related errors

• shard_hint is deprecated in cluster mode
• All keys involved in a cluster transaction must map to the…
• At least a command with a key is needed to identify a node
• At least a command with a key is needed to identify a node
• Cannot identify slot number for command

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/3c99b168e173c3d7. Report an issue: GitHub.

Appendix: source

Thrown at redis/asyncio/cluster.py:1457

            command_name=command,
            duration_seconds=time.monotonic() - start_time,
            connection=target_node,
            error=e,
        )
        raise e

    def pipeline(
        self, transaction: Optional[Any] = None, shard_hint: Optional[Any] = None
    ) -> "ClusterPipeline":
        """
        Create & return a new :class:`~.ClusterPipeline` object.

        Cluster implementation of pipeline does not support transaction or shard_hint.

        :raises RedisClusterException: if transaction or shard_hint are truthy values
        """
        if shard_hint:
            raise RedisClusterException("shard_hint is deprecated in cluster mode")

        return ClusterPipeline(self, transaction)

    def pubsub(
        self,
        node: Optional["ClusterNode"] = None,
        host: Optional[str] = None,
        port: Optional[int] = None,
        **kwargs: Any,
    ) -> "ClusterPubSub":
        """
        Create and return a ClusterPubSub instance.

        Allows passing a ClusterNode, or host&port, to get a pubsub instance
        connected to the specified node

        :param node: ClusterNode to connect to
        :param host: Host of the node to connect to

View on GitHub (pinned to 6a6b581b48)