redis/redis-py · error · RedisClusterException

method script_load_for_pipeline() is not implemented

Error message

method script_load_for_pipeline() is not implemented

What it means

ClusterPipeline.script_load_for_pipeline() routes to AbstractStrategy.script_load_for_pipeline() (redis/cluster.py:4111), which unconditionally raises. This helper exists on the standalone Pipeline to SCRIPT LOAD a script and stash its SHA for later EVAL within the same pipeline; the cluster pipeline cannot implement it because EVAL SHA dispatch depends on per-slot routing and the SHA must exist on every node that may execute it.

Source

Thrown at redis/cluster.py:4113

    @abstractmethod
    def reset(self):
        pass

    def exists(self, *keys):
        return self.execute_command("EXISTS", *keys)

    def eval(self):
        """ """
        raise RedisClusterException("method eval() is not implemented")

    def load_scripts(self):
        """ """
        raise RedisClusterException("method load_scripts() is not implemented")

    def script_load_for_pipeline(self, *args, **kwargs):
        """ """
        raise RedisClusterException(
            "method script_load_for_pipeline() is not implemented"
        )

    def annotate_exception(self, exception, number, command):
        """
        Provides extra context to the exception prior to it being handled
        """
        cmd = " ".join(map(safe_str, command))
        msg = (
            f"Command # {number} ({truncate_text(cmd)}) of pipeline "
            f"caused error: {exception.args[0]}"
        )
        exception.args = (msg,) + exception.args[1:]


class PipelineStrategy(AbstractStrategy):
    def __init__(self, pipe: ClusterPipeline):
        super().__init__(pipe)

View on GitHub (pinned to da03cdc7e8)

Solutions

SCRIPT LOAD the script on all primaries with rc.script_load(script, target_nodes=RedisCluster.PRIMARIES), then issue EVALSHA on the client within the pipeline body.
Switch to Redis Functions (FUNCTION LOAD) which cluster-routes correctly, eliminating the need for this helper.
Drop the call if you only need EVAL (not EVALSHA); use rc.eval(...) directly on the client.

Example fix

# before
pipe = rc.pipeline()
pipe.script_load_for_pipeline(script)

# after
sha = rc.script_load(script, target_nodes=RedisCluster.PRIMARIES)
pipe.set('k', 'v')  # build your pipeline normally
rc.evalsha(sha, numkeys, *keys)

Defensive patterns

Strategy: validation

Validate before calling

from redis.cluster import RedisCluster

def preload_for_pipeline(client, script):
    if isinstance(client, RedisCluster):
        return client.script_load(script, target_nodes=RedisCluster.PRIMARIES)
    pipe = client.pipeline()
    pipe.script_load_for_pipeline(script)
    pipe.execute()
    return None

Type guard

from redis.cluster import RedisCluster

def is_cluster_client(client) -> bool:
    return isinstance(client, RedisCluster)

Try / catch

from redis.exceptions import RedisClusterException

try:
    pipe.script_load_for_pipeline(script)
except RedisClusterException:
    sha = rc.script_load(script, target_nodes=RedisCluster.PRIMARIES)

Prevention

Replace script_load_for_pipeline() with explicit SCRIPT LOAD on all primaries for cluster.
Use EVAL directly on the client or FCALL via Functions.
Document the cluster incompatibility of this helper anywhere it appears.

When it happens

Trigger: Calling pipe.script_load_for_pipeline(script) on a RedisCluster pipeline. Path: ClusterPipeline.script_load_for_pipeline (redis/cluster.py:3742) -> strategy.script_load_for_pipeline() -> raises at redis/cluster.py:4113.

Common situations: Reusing a standalone pipeline helper that bundles SCRIPT LOAD + EVALSHA in one pipeline against a cluster. Older tutorial/sample code copied into a cluster app.

Related errors

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