redis/redis-py · error · RedisClusterException

The 'retry' argument cannot be used in kwargs when running i

Error message

The 'retry' argument cannot be used in kwargs when running in cluster mode.

What it means

Raised in `RedisCluster.__init__` when `'retry'` is present in kwargs. The retry configuration for the cluster client must be supplied via the dedicated top-level `retry` constructor parameter (it is applied at the cluster-routing layer, not per-node), so passing retry inside connection kwargs is rejected to avoid it being silently applied to individual node connections without the cluster-level orchestration.

Source

Thrown at redis/cluster.py:826

            RedisClusterException:
                - db (Redis do not support database SELECT in cluster mode)

        """
        if startup_nodes is None:
            startup_nodes = []

        if "db" in kwargs:
            # Argument 'db' is not possible to use in cluster mode
            raise RedisClusterException(
                "Argument 'db' is not possible to use in cluster mode"
            )

        if "retry" in kwargs:
            # Argument 'retry' is not possible to be used in kwargs when in cluster mode
            # the kwargs are set to the lower level connections to the cluster nodes
            # and there we provide retry configuration without retries allowed.
            # The retries should be handled on cluster client level.
            raise RedisClusterException(
                "The 'retry' argument cannot be used in kwargs when running in cluster mode."
            )

        # Get the startup node/s
        from_url = False
        if url is not None:
            from_url = True
            url_options = parse_url(url)
            if "path" in url_options:
                raise RedisClusterException(
                    "RedisCluster does not currently support Unix Domain "
                    "Socket connections"
                )
            if "db" in url_options and url_options["db"] != 0:
                # Argument 'db' is not possible to use in cluster mode
                raise RedisClusterException(
                    "A ``db`` querystring option can only be 0 in cluster mode"
                )

View on GitHub (pinned to da03cdc7e8)

Solutions

Pass retry as the explicit constructor argument: `RedisCluster(host=..., port=..., retry=Retry(backoff, retries))`.
When sharing a config dict, pop `retry` out for cluster clients: `retry = kwargs.pop('retry', None)`.
Check that the kwarg name is not shadowed by a helper that bundles everything into **kwargs.

Example fix

# before
kwargs = {'retry': Retry(NoBackoff(), 3)}
rc = RedisCluster(host='h', port=7000, **kwargs)  # raises

# after
rc = RedisCluster(host='h', port=7000, retry=Retry(NoBackoff(), 3))

Defensive patterns

Strategy: validation

Validate before calling

retry = kwargs.pop('retry', None)  # never pass retry inside kwargs
rc = RedisCluster(host='h', port=7000, retry=retry, **kwargs)

Type guard

def cluster_kwargs_ok(kwargs: dict) -> bool:
    return 'retry' not in kwargs

Prevention

Pass retry as the explicit RedisCluster(retry=...) parameter.
Do not bundle retry into shared connection-kwargs dicts.

When it happens

Trigger: Calling `RedisCluster(..., retry=Retry(...))` where `retry` is mistakenly placed in a kwargs/connection_kwargs dict instead of as the constructor's explicit `retry` parameter; spreading a generic Redis client config into RedisCluster.

Common situations: Sharing config dicts between standalone Redis() and RedisCluster(); migrating retry settings and accidentally passing them as connection kwargs.

Related errors

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