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 in `RedisCluster.__init__` when the user passes `db=<n>` as a keyword argument. Redis Cluster does not support the SELECT command (all keys are partitioned across the 16384 slot space and there is a single logical keyspace), so any non-zero — in fact any — `db` kwarg is rejected with RedisClusterException to prevent silent misuse.

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 da03cdc7e8)

Solutions

Remove the `db` kwarg from the RedisCluster constructor call — cluster mode uses a single logical database.
If sharing a config dict, strip `db` for cluster clients: `{k:v for k,v in cfg.items() if k != 'db'}`.
For URLs, ensure the DSN has no `/db` path component (or use `/0`).

Example fix

# before
rc = RedisCluster(host='localhost', port=7000, db=1)  # raises

# after
rc = RedisCluster(host='localhost', port=7000)

Defensive patterns

Strategy: validation

Validate before calling

kwargs = {'host': 'h', 'port': 7000}
assert 'db' not in kwargs, 'db is invalid for cluster mode'
rc = RedisCluster(**kwargs)

Type guard

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

Prevention

Never pass db to RedisCluster.
When sharing config, strip db for cluster clients.

When it happens

Trigger: Constructing `RedisCluster(host=..., port=..., db=1)` or passing `db` via connection kwargs to RedisCluster. The check `'db' in kwargs` triggers before any connection is made.

Common situations: Reusing standalone-Redis connection kwargs (where `db=0..15` is normal) when switching to RedisCluster; passing a shared config dict that includes `db`; URL-based configs that include a db index.

Related errors

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