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 by RedisCluster.__init__ when a redis:// URL includes a db querystring/path component whose value is not 0. Same rationale as 193 (cluster mode forbids SELECT), but this branch specifically catches the URL-encoded db, e.g. redis://host:7000/2 or redis://host:7000?db=2.

Solutions

  1. Drop the db from the URL: redis://localhost:7000 or redis://localhost:7000/0.
  2. If your config templating forces a db, set it to 0 for cluster URLs.
  3. Remember only db=0 is permitted; any other value is rejected.

Example fix

// before
client = RedisCluster.from_url('redis://localhost:7000/1')  # RedisClusterException

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

Strategy: validation

Validate before calling

from urllib.parse import urlparse, parse_qs
p = urlparse(url)
qs_db = parse_qs(p.query).get('db', ['0'])
path_db = p.path.strip('/') or '0'
db = qs_db[0] if qs_db else path_db
if db != '0':
    raise ValueError('Cluster URL db must be 0')
client = RedisCluster.from_url(url)

Type guard

def cluster_url_db_is_zero(url: str) -> bool:
    from urllib.parse import urlparse, parse_qs
    p = urlparse(url)
    db = (parse_qs(p.query).get('db', ['0'])[0]) if 'db' in parse_qs(p.query) else (p.strip('/').split('/')[-1] if '/' in p.path else '0')
    return db == '0'

Try / catch

from redis.cluster import RedisClusterException
try:
    client = RedisCluster.from_url(url)
except RedisClusterException as e:
    if 'db' in str(e):
        # normalize db to 0
        url = url.rstrip('/0123456789').rstrip('/')
        client = RedisCluster.from_url(url)
    else:
        raise

Prevention

When it happens

Trigger: RedisCluster.from_url('redis://localhost:7000/1') or a URL with ?db=2. parse_url extracts db != 0 and the guard at cluster.py:840 fires.

Common situations: Reusing a standalone-style URL (which commonly has /0, /1) for a cluster client; config templating that always emits a db segment.

Related errors

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

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