{"record":{"id":"8323187eadb07bb2","repo":"redis/redis-py","slug":"a-db-querystring-option-can-only-be-0-in-clust","errorCode":null,"errorMessage":"A ``db`` querystring option can only be 0 in cluster mode","messagePattern":"A ``db`` querystring option can only be 0 in cluster mode","errorType":"exception","errorClass":"RedisClusterException","httpStatus":null,"severity":"error","filePath":"redis/cluster.py","lineNumber":842,"sourceCode":"            # and there we provide retry configuration without retries allowed.\n            # The retries should be handled on cluster client level.\n            raise RedisClusterException(\n                \"The 'retry' argument cannot be used in kwargs when running in cluster mode.\"\n            )\n\n        # Get the startup node/s\n        from_url = False\n        if url is not None:\n            from_url = True\n            url_options = parse_url(url)\n            if \"path\" in url_options:\n                raise RedisClusterException(\n                    \"RedisCluster does not currently support Unix Domain \"\n                    \"Socket connections\"\n                )\n            if \"db\" in url_options and url_options[\"db\"] != 0:\n                # Argument 'db' is not possible to use in cluster mode\n                raise RedisClusterException(\n                    \"A ``db`` querystring option can only be 0 in cluster mode\"\n                )\n            kwargs.update(url_options)\n            host = kwargs.get(\"host\")\n            port = kwargs.get(\"port\", port)\n            startup_nodes.append(ClusterNode(host, port))\n        elif host is not None and port is not None:\n            startup_nodes.append(ClusterNode(host, port))\n        elif len(startup_nodes) == 0:\n            # No startup node was provided\n            raise RedisClusterException(\n                \"RedisCluster requires at least one node to discover the \"\n                \"cluster. Please provide one of the followings:\\n\"\n                \"1. host and port, for example:\\n\"\n                \" RedisCluster(host='localhost', port=6379)\\n\"\n                \"2. list of startup nodes, for example:\\n\"\n                \" RedisCluster(startup_nodes=[ClusterNode('localhost', 6379),\"\n                \" ClusterNode('localhost', 6378)])\"","sourceCodeStart":824,"sourceCodeEnd":860,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/cluster.py#L824-L860","documentation":"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.","triggerScenarios":"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.","commonSituations":"Reusing a standalone-style URL (which commonly has /0, /1) for a cluster client; config templating that always emits a db segment.","solutions":["Drop the db from the URL: redis://localhost:7000 or redis://localhost:7000/0.","If your config templating forces a db, set it to 0 for cluster URLs.","Remember only db=0 is permitted; any other value is rejected."],"exampleFix":"// before\nclient = RedisCluster.from_url('redis://localhost:7000/1')  # RedisClusterException\n\n// after\nclient = RedisCluster.from_url('redis://localhost:7000/0')","handlingStrategy":"validation","validationCode":"from urllib.parse import urlparse, parse_qs\np = urlparse(url)\nqs_db = parse_qs(p.query).get('db', ['0'])\npath_db = p.path.strip('/') or '0'\ndb = qs_db[0] if qs_db else path_db\nif db != '0':\n    raise ValueError('Cluster URL db must be 0')\nclient = RedisCluster.from_url(url)","typeGuard":"def cluster_url_db_is_zero(url: str) -> bool:\n    from urllib.parse import urlparse, parse_qs\n    p = urlparse(url)\n    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')\n    return db == '0'","tryCatchPattern":"from redis.cluster import RedisClusterException\ntry:\n    client = RedisCluster.from_url(url)\nexcept RedisClusterException as e:\n    if 'db' in str(e):\n        # normalize db to 0\n        url = url.rstrip('/0123456789').rstrip('/')\n        client = RedisCluster.from_url(url)\n    else:\n        raise","preventionTips":["Omit the db segment from cluster URLs, or set it to 0.","Templated config should default db=0 for cluster endpoints.","Validate URLs in config-loading code before passing to from_url."],"tags":["cluster","config","url","api-misuse"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}