redis/redis-py · error · RedisClusterException

unlinking multiple keys is not implemented in pipeline comma

Error message

unlinking multiple keys is not implemented in pipeline command

What it means

PipelineStrategy.unlink() (redis/cluster.py:4552) raises when len(names) != 1. UNLINK is the non-blocking DEL; the cluster pipeline restricts it to a single key per call for the same slot-routing reason as DEL. Queue one UNLINK per key.

Source

Thrown at redis/cluster.py:4554

            "method watch() is not supported outside of transactional context"
        )

    def unwatch(self, *names):
        raise RedisClusterException(
            "method unwatch() is not supported outside of transactional context"
        )

    def delete(self, *names):
        if len(names) != 1:
            raise RedisClusterException(
                "deleting multiple keys is not implemented in pipeline command"
            )

        return self.execute_command("DEL", names[0])

    def unlink(self, *names):
        if len(names) != 1:
            raise RedisClusterException(
                "unlinking multiple keys is not implemented in pipeline command"
            )

        return self.execute_command("UNLINK", names[0])


class TransactionStrategy(AbstractStrategy):
    NO_SLOTS_COMMANDS = {"UNWATCH"}
    IMMEDIATE_EXECUTE_COMMANDS = {"WATCH", "UNWATCH"}
    UNWATCH_COMMANDS = {"DISCARD", "EXEC", "UNWATCH"}
    SLOT_REDIRECT_ERRORS = (AskError, MovedError)
    CONNECTION_ERRORS = (
        ConnectionError,
        OSError,
        ClusterDownError,
        SlotNotCoveredError,
    )

View on GitHub (pinned to da03cdc7e8)

Solutions

Queue one UNLINK per key: for k in keys: pipe.unlink(k).
Group keys under a shared hash tag if you want them on one slot, but still call unlink once per key in the pipeline.
Outside a pipeline, loop rc.unlink(k) per key (or per same-slot batch).

Example fix

# before
pipe = rc.pipeline()
pipe.unlink('k1', 'k2')  # raises: unlinking multiple keys
pipe.execute()

# after
pipe = rc.pipeline()
for k in ['k1', 'k2']:
    pipe.unlink(k)
pipe.execute()

Defensive patterns

Strategy: validation

Validate before calling

def pipeline_unlink(pipe, keys):
    for k in keys:
        pipe.unlink(k)
    return pipe

Try / catch

from redis.exceptions import RedisClusterException

try:
    pipe.unlink(*keys)
except RedisClusterException as e:
    if 'multiple keys' in str(e):
        for k in keys:
            pipe.unlink(k)
    else:
        raise

Prevention

Queue one UNLINK per key in a cluster pipeline.
Use a helper that iterates keys instead of passing them all at once.
Apply the same constraint to DEL and UNLINK in cluster pipeline code.

When it happens

Trigger: Calling pipe.unlink('k1','k2') (count != 1) on a cluster pipeline.

Common situations: Bulk-cleanup code that uses UNLINK for large keys, ported from standalone redis-py. Background jobs that unlink many keys in one pipeline call.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/31c9cc5e63e79836.json. Report an issue: GitHub.