redis/redis-py · error · RedisClusterException

A ``db`` querystring option can only be 0 in cluster mode

Error message

A ``db`` querystring option can only be 0 in cluster mode

What it means

Raised in `RedisCluster.__init__` URL-handling branch when the parsed URL contains a `db` query/path option whose value is not 0. Since cluster mode has a single logical database and SELECT is unsupported, the only tolerated value is 0; any other index is rejected with RedisClusterException.

Source

Thrown at redis/cluster.py:842

            # 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"
                )
            kwargs.update(url_options)
            host = kwargs.get("host")
            port = kwargs.get("port", port)
            startup_nodes.append(ClusterNode(host, port))
        elif host is not None and port is not None:
            startup_nodes.append(ClusterNode(host, port))
        elif len(startup_nodes) == 0:
            # No startup node was provided
            raise RedisClusterException(
                "RedisCluster requires at least one node to discover the "
                "cluster. Please provide one of the followings:\n"
                "1. host and port, for example:\n"
                " RedisCluster(host='localhost', port=6379)\n"
                "2. list of startup nodes, for example:\n"
                " RedisCluster(startup_nodes=[ClusterNode('localhost', 6379),"
                " ClusterNode('localhost', 6378)])"

View on GitHub (pinned to da03cdc7e8)

Solutions

  1. Drop the db index from the cluster URL: `redis://host:7000` or `redis://host:7000/0`.
  2. Adjust templating so cluster URLs omit the db segment.
  3. If you need logical isolation in cluster mode, use key-prefix namespacing instead of db indexes.

Example fix

# before
rc = RedisCluster.from_url('redis://localhost:7000/1')  # raises

# after
rc = RedisCluster.from_url('redis://localhost:7000/0')
Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse
u = urlparse(url)
# path like '/1' or query '?db=2'
db = u.path.strip('/') if u.path not in ('', '/') else '0'
assert db in ('', '0'), 'db must be 0 in cluster mode'

Type guard

def cluster_url_db_ok(url: str) -> bool:
    u = urlparse(url)
    return u.path in ('', '/', '/0')

Prevention

When it happens

Trigger: Calling `RedisCluster.from_url('redis://host:7000/1')` or `RedisCluster(url='redis://...?db=2')`. The URL parser extracts `db` and the constructor checks `url_options['db'] != 0`.

Common situations: Porting a standalone Redis URL that uses `/2` for a logical database into a cluster client; templated config strings that always append a db index.

Related errors

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