redis/redis-py · error · RedisClusterException

Argument 'db' is not possible to use in cluster mode

Error message

Argument 'db' is not possible to use in cluster mode

What it means

Raised by RedisCluster.__init__ when 'db' is present in kwargs. Redis Cluster does not support SELECT — all keys are addressed by hash slot across nodes, so a logical database index is meaningless. The constructor rejects it eagerly to avoid silent misconfiguration.

Solutions

Remove the db argument from your RedisCluster(...) call.
If loading config from a shared dict, strip/ignore the db key for cluster clients.
Remember cluster mode implies db 0 only; do not attempt to SELECT.

Example fix

// before
client = RedisCluster(host='localhost', port=7000, db=1)  # RedisClusterException

// after
client = RedisCluster(host='localhost', port=7000)

Defensive patterns

Strategy: validation

Validate before calling

kwargs.pop('db', None)  # strip db before constructing cluster client
client = RedisCluster(host='localhost', port=7000, **kwargs)

Type guard

def kwargs_safe_for_cluster(kwargs) -> bool:
    return 'db' not in kwargs

Try / catch

from redis.cluster import RedisClusterException
try:
    client = RedisCluster(host='localhost', port=7000, db=db)
except RedisClusterException:
    client = RedisCluster(host='localhost', port=7000)

Prevention

Never pass db to a cluster client; cluster mode implies db 0.
When sharing config between standalone and cluster clients, strip db for the cluster path.
Centralize client construction in a factory that enforces cluster vs. standalone rules.

When it happens

Trigger: RedisCluster(host=..., port=..., db=1) or RedisCluster.from_url('redis://.../1') where the db leaks into kwargs (the from_url form is caught separately at 196). Direct kwarg use hits client.py-level guard at cluster.py:817.

Common situations: Copy-pasting a standalone Redis(...) config (with db=N) into a RedisCluster(...) call; environment-based config that injects db for all clients.

Related errors

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

Appendix: source

Thrown at redis/cluster.py:817

            If not provided and protocol is RESP3, the maintenance notifications
            will be enabled by default (logic is included in the NodesManager
            initialization).
        :**kwargs:
            Extra arguments that will be sent into Redis instance when created
            (See Official redis-py doc for supported kwargs - the only limitation
            is that you can't provide 'retry' object as part of kwargs.
            [https://github.com/andymccurdy/redis-py/blob/master/redis/client.py])
            Some kwargs are not supported and will raise a
            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:

View on GitHub (pinned to 6a6b581b48)