redis/redis-py · error · RedisClusterException

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

Error message

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

What it means

Raised by RedisCluster.__init__ when 'retry' is present in kwargs. Retry behavior in cluster mode is managed at the cluster-client level (self.retry) because retries must coordinate with MOVED/ASK redirection and slot ownership; a per-connection retry object would conflict with that logic. Pass retry as the dedicated top-level constructor argument instead.

Solutions

Pass retry as the explicit named argument: RedisCluster(host=..., port=..., retry=my_retry).
If assembling kwargs dynamically, pop 'retry' out and pass it positionally/named.
Confirm cluster_error_retry_attempts (constructor param) is used to size the cluster-level retry instead of a per-connection Retry object.

Example fix

// before
kwargs = {'retry': Retry(backoff, 3), 'socket_timeout': 1}
client = RedisCluster(host='localhost', port=7000, **kwargs)  # RedisClusterException

// after
retry = kwargs.pop('retry')
client = RedisCluster(host='localhost', port=7000, retry=retry, **kwargs)

Defensive patterns

Strategy: validation

Validate before calling

retry = kwargs.pop('retry', None)
client = RedisCluster(host='localhost', port=7000, retry=retry, **kwargs)

Type guard

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

Try / catch

from redis.cluster import RedisClusterException
try:
    client = RedisCluster(host='localhost', port=7000, **kwargs)
except RedisClusterException as e:
    if 'retry' in str(e):
        retry = kwargs.pop('retry')
        client = RedisCluster(host='localhost', port=7000, retry=retry, **kwargs)
    else:
        raise

Prevention

Pass retry as the named constructor argument for cluster clients, never inside kwargs.
Filter shared kwargs dicts for cluster-incompatible keys before construction.
Use cluster_error_retry_attempts to size cluster-level retry instead of a per-connection Retry.

When it happens

Trigger: RedisCluster(host=..., port=..., retry=my_retry) — here retry lands in kwargs rather than the named parameter slot. Typically happens when constructing kwargs as a dict and passing via **kwargs without filtering.

Common situations: Building a generic kwargs dict for both standalone and cluster clients; upgrading from standalone Redis(retry=...) to cluster without adjusting call style; passing retry inside connection_kwargs.

Related errors

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

Appendix: 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 6a6b581b48)