{"record":{"id":"606c9d5f08a8d951","repo":"redis/redis-py","slug":"argument-db-must-be-0-or-none-in-cluster-mode","errorCode":null,"errorMessage":"Argument 'db' must be 0 or None in cluster mode","messagePattern":"Argument 'db' must be 0 or None in cluster mode","errorType":"exception","errorClass":"RedisClusterException","httpStatus":null,"severity":"error","filePath":"redis/asyncio/cluster.py","lineNumber":462,"sourceCode":"        ssl_ca_certs: str | None = None,\n        ssl_ca_data: str | None = None,\n        ssl_cert_reqs: \"str | VerifyMode\" = \"required\",\n        ssl_include_verify_flags: List[\"VerifyFlags\"] | None = None,\n        ssl_exclude_verify_flags: List[\"VerifyFlags\"] | None = None,\n        ssl_certfile: str | None = None,\n        ssl_check_hostname: bool = True,\n        ssl_keyfile: str | None = None,\n        ssl_min_version: \"TLSVersion | None\" = None,\n        ssl_ciphers: str | None = None,\n        protocol: int | None = None,\n        legacy_responses: bool = True,\n        address_remap: Callable[[Tuple[str, int]], Tuple[str, int]] | None = None,\n        event_dispatcher: EventDispatcher | None = None,\n        policy_resolver: AsyncPolicyResolver = AsyncStaticPolicyResolver(),\n        maint_notifications_config: MaintNotificationsConfig | None = None,\n    ) -> None:\n        if db:\n            raise RedisClusterException(\n                \"Argument 'db' must be 0 or None in cluster mode\"\n            )\n\n        if path:\n            raise RedisClusterException(\n                \"Unix domain socket is not supported in cluster mode\"\n            )\n\n        if (not host or not port) and not startup_nodes:\n            raise RedisClusterException(\n                \"RedisCluster requires at least one node to discover the cluster.\\n\"\n                \"Please provide one of the following or use RedisCluster.from_url:\\n\"\n                '   - host and port: RedisCluster(host=\"localhost\", port=6379)\\n'\n                \"   - startup_nodes: RedisCluster(startup_nodes=[\"\n                'ClusterNode(\"localhost\", 6379), ClusterNode(\"localhost\", 6380)])'\n            )\n\n        computed_driver_info = resolve_driver_info(driver_info, lib_name, lib_version)","sourceCodeStart":444,"sourceCodeEnd":480,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/asyncio/cluster.py#L444-L480","documentation":"Raised in RedisCluster.__init__ when the db argument is non-zero. Redis Cluster only operates on logical database 0 (the cluster bus, slot routing, and pubsub shards assume db 0), so passing db=1..15 is rejected at construction. The message is literal: db must be 0 or None.","triggerScenarios":"RedisCluster(host=..., port=..., db=1); passing a URL with /1 to RedisCluster.from_url; sharing a db-indexed config object between a standalone Redis() and a RedisCluster().","commonSituations":"Reusing a standalone-Redis connection helper that defaults db to a non-zero value; copy-pasting a redis:// URL that includes a database number for a cluster deployment.","solutions":["Remove the db argument (or set db=0) when constructing RedisCluster.","If you built the URL with a database suffix, strip it for cluster clients.","Centralize connection config and assert db in (0, None) for cluster clients."],"exampleFix":"// before\nclient = RedisCluster(host='localhost', port=7000, db=1)\n// after\nclient = RedisCluster(host='localhost', port=7000, db=0)","handlingStrategy":"validation","validationCode":"assert db in (0, None), f'db must be 0 or None for cluster, got {db}'\nclient = RedisCluster(host=..., port=..., db=db)","typeGuard":"def is_valid_cluster_db(db: int | None) -> bool:\n    return db in (0, None)","tryCatchPattern":"from redis.exceptions import RedisClusterException\ntry:\n    client = RedisCluster(host=..., port=..., db=db)\nexcept RedisClusterException as e:\n    if \"db' must be 0\" in str(e):\n        client = RedisCluster(host=..., port=..., db=0)\n    else:\n        raise","preventionTips":["Branch connection builders: cluster clients must use db=0.","Validate db before constructing the client."],"tags":["cluster","configuration","init","database"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}