What causes "Argument 'db' must be 0 or None in cluster mode" in redis/redis-py?

Remove the db argument (or set db=0) when constructing RedisCluster.

redis/redis-py · error · RedisClusterException

Argument 'db' must be 0 or None in cluster mode

Error message

Argument 'db' must be 0 or None in cluster mode

What it means

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.

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.

Example fix

// before
client = RedisCluster(host='localhost', port=7000, db=1)
// after
client = RedisCluster(host='localhost', port=7000, db=0)

Defensive patterns

Strategy: validation

Validate before calling

assert db in (0, None), f'db must be 0 or None for cluster, got {db}'
client = RedisCluster(host=..., port=..., db=db)

Type guard

def is_valid_cluster_db(db: int | None) -> bool:
    return db in (0, None)

Try / catch

from redis.exceptions import RedisClusterException
try:
    client = RedisCluster(host=..., port=..., db=db)
except RedisClusterException as e:
    if "db' must be 0" in str(e):
        client = RedisCluster(host=..., port=..., db=0)
    else:
        raise

Prevention

Branch connection builders: cluster clients must use db=0.
Validate db before constructing the client.

When it happens

Trigger: 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().

Common situations: 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.

Related errors

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

Appendix: source

Thrown at redis/asyncio/cluster.py:462

        ssl_ca_certs: str | None = None,
        ssl_ca_data: str | None = None,
        ssl_cert_reqs: "str | VerifyMode" = "required",
        ssl_include_verify_flags: List["VerifyFlags"] | None = None,
        ssl_exclude_verify_flags: List["VerifyFlags"] | None = None,
        ssl_certfile: str | None = None,
        ssl_check_hostname: bool = True,
        ssl_keyfile: str | None = None,
        ssl_min_version: "TLSVersion | None" = None,
        ssl_ciphers: str | None = None,
        protocol: int | None = None,
        legacy_responses: bool = True,
        address_remap: Callable[[Tuple[str, int]], Tuple[str, int]] | None = None,
        event_dispatcher: EventDispatcher | None = None,
        policy_resolver: AsyncPolicyResolver = AsyncStaticPolicyResolver(),
        maint_notifications_config: MaintNotificationsConfig | None = None,
    ) -> None:
        if db:
            raise RedisClusterException(
                "Argument 'db' must be 0 or None in cluster mode"
            )

        if path:
            raise RedisClusterException(
                "Unix domain socket is not supported in cluster mode"
            )

        if (not host or not port) and not startup_nodes:
            raise RedisClusterException(
                "RedisCluster requires at least one node to discover the cluster.\n"
                "Please provide one of the following or use RedisCluster.from_url:\n"
                '   - host and port: RedisCluster(host="localhost", port=6379)\n'
                "   - startup_nodes: RedisCluster(startup_nodes=["
                'ClusterNode("localhost", 6379), ClusterNode("localhost", 6380)])'
            )

        computed_driver_info = resolve_driver_info(driver_info, lib_name, lib_version)

View on GitHub (pinned to 6a6b581b48)