What causes "shard_hint is deprecated in cluster mode" in redis/redis-py?

Remove the shard_hint argument from your pipeline() call; the cluster client handles connection routing automatically.

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 as a RedisClusterException by pipeline() when shard_hint is passed with a truthy value. In standalone Redis, shard_hint selects a connection in a sharded pool, but Redis Cluster manages its own per-slot/per-node connection pools, so the concept does not apply and is explicitly rejected at cluster.py:1234-1235.

Solutions

Remove the shard_hint argument from your pipeline() call; the cluster client handles connection routing automatically.
If you were using shard_hint for manual sharding, rely on hash tags ({tag}) in keys to control slot placement instead.

Example fix

// before
pipe = client.pipeline(transaction=True, shard_hint='shard1')

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

Defensive patterns

Strategy: validation

Validate before calling

# Never pass shard_hint to pipeline() in cluster mode
# Remove shard_hint entirely from the call

Type guard

null

Try / catch

null

Prevention

Never pass shard_hint to RedisCluster.pipeline(); the cluster client manages connection routing.
When porting from standalone Redis, audit and remove shard_hint arguments.
Use hash tags ({tag}) if you need to control key slot placement.

When it happens

Trigger: Calling client.pipeline(transaction=True, shard_hint='something') on a RedisCluster instance. Any non-None truthy value for shard_hint triggers the guard.

Common situations: Porting code from redis.Redis (standalone) to RedisCluster that previously used shard_hint for a custom sharded connection pool, or copy-paste from a non-cluster example.

Related errors

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

Appendix: source

Thrown at redis/cluster.py:1235

        from redis.keyspace_notifications import ClusterKeyspaceNotifications

        return ClusterKeyspaceNotifications(
            self,
            key_prefix=key_prefix,
            ignore_subscribe_messages=ignore_subscribe_messages,
        )

    def pipeline(self, transaction=None, shard_hint=None):
        """
        Cluster impl:
            Pipelines do not work in cluster mode the same way they
            do in normal mode. Create a clone of this object so
            that simulating pipelines will work correctly. Each
            command will be called directly when used and
            when calling execute() will only return the result stack.
        """
        if shard_hint:
            raise RedisClusterException("shard_hint is deprecated in cluster mode")

        return ClusterPipeline(
            nodes_manager=self.nodes_manager,
            commands_parser=self.commands_parser,
            startup_nodes=self.nodes_manager.startup_nodes,
            result_callbacks=self.result_callbacks,
            cluster_response_callbacks=self.cluster_response_callbacks,
            read_from_replicas=self.read_from_replicas,
            load_balancing_strategy=self.load_balancing_strategy,
            reinitialize_steps=self.reinitialize_steps,
            retry=self.retry,
            lock=self._lock,
            transaction=transaction,
            event_dispatcher=self._event_dispatcher,
        )

    def lock(
        self,

View on GitHub (pinned to 6a6b581b48)