redis/redis-py · error · RedisClusterException

At least a command with a key is needed to identify a node

Error message

At least a command with a key is needed to identify a node

What it means

Raised by TransactionStrategy._get_client_and_connection_for_transaction (redis/asyncio/cluster.py:3117) when self._pipeline_slots is empty. A cluster transaction must pin a single node, which requires at least one keyed command to resolve a slot. If only slot-agnostic commands (e.g. UNWATCH) were queued, there is no slot from which to derive the owning node, so the transaction cannot be executed. Queue at least one keyed command before execute().

Solutions

  1. Ensure the pipeline contains at least one keyed command (GET/SET/etc.) before execute()
  2. If you only need slot-agnostic commands, send them directly on the client rather than through a transactional pipeline
  3. For zero-key scripts, either pair them with a keyed command or send them directly via client.eval()

Example fix

// before
pipe = client.pipeline(transaction=True)
await pipe.unwatch()
await pipe.execute()
// after - send slot-agnostic commands directly
await client.unwatch()
Defensive patterns

Strategy: validation

Validate before calling

if not pipe._command_queue:  # or track that a keyed command was added
    raise ValueError('add at least one keyed command before execute()')

Try / catch

try:
    await pipe.execute()
except RedisClusterException as e:
    if 'At least a command with a key' in str(e):
        # add a keyed command or skip the transaction
        ...

Prevention

When it happens

Trigger: Building a ClusterPipeline and calling execute() / multi()/EXEC after only slot-agnostic commands (UNWATCH, or zero-key EVAL) with no keyed command ever added; calling watch()/unwatch() cycle without a keyed command in between.

Common situations: Using pipeline purely to send ADMIN/CONFIG-style commands inside a transaction; empty or aborted transactions that only contained UNWATCH.

Related errors

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

Appendix: source

Thrown at redis/asyncio/cluster.py:3129

            # Prior slots came only from zero-key scripts; retarget.
            self._pipeline_slots.clear()
        if slot_number is not None:
            self._transaction_has_keyed_slot = True
        return slot_number

    def _get_client_and_connection_for_transaction(
        self,
    ) -> Tuple[ClusterNode, Connection]:
        """
        Find a connection for a pipeline transaction.

        For running an atomic transaction, watch keys ensure that contents have not been
        altered as long as the watch commands for those keys were sent over the same
        connection. So once we start watching a key, we fetch a connection to the
        node that owns that slot and reuse it.
        """
        if not self._pipeline_slots:
            raise RedisClusterException(
                "At least a command with a key is needed to identify a node"
            )

        node: ClusterNode = self._pipe.cluster_client.nodes_manager.get_node_from_slot(
            list(self._pipeline_slots)[0], False
        )
        self._transaction_node = node

        if not self._transaction_connection:
            connection: Connection = self._transaction_node.acquire_connection()
            self._transaction_connection = connection

        return self._transaction_node, self._transaction_connection

    def execute_command(self, *args: Union[KeyT, EncodableT], **kwargs: Any) -> "Any":
        # Given the limitation of ClusterPipeline sync API, we have to run it in thread.
        response = None
        error = None

View on GitHub (pinned to 6a6b581b48)