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 by RedisCluster.__init__ (redis/asyncio/cluster.py:461) when a non-zero `db` argument is passed. Redis Cluster only supports database 0 (the CLUSTER subcommands and slot routing assume db 0), so selecting another db is invalid. The constructor rejects it immediately with RedisClusterException.

Source

Thrown at redis/asyncio/cluster.py:461

        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 da03cdc7e8)

Solutions

1. Drop the db argument (defaults to 0) or set db=0 / db=None explicitly.
2. If you selected a db for namespace isolation, use key prefixes or separate clusters instead.
3. When constructing from a URL, ensure the path is /0 or absent: redis://host:port/0.

Example fix

// before
c = RedisCluster(host='localhost', port=16379, db=1)
// after
c = RedisCluster(host='localhost', port=16379)  # db defaults to None/0

if db not in (0, None):
    raise ValueError('RedisCluster only supports db=0')
c = RedisCluster(host=host, port=port, db=db)

When it happens

Trigger: Constructing RedisCluster(db=1, ...) or passing a URL like redis://host:6379/3 to a cluster client. The very first validation in __init__ checks `if db:`.

Common situations: Reusing a standalone-Redis config (which used db=N for logical separation) against a cluster endpoint; building RedisCluster from a shared settings object that carries a db field.

Related errors

• Unix domain socket is not supported in cluster mode
• RedisCluster requires at least one node to discover the clus
• Maintenance notifications are only supported with RESP versi
• Maintenance notifications handlers on connection are only su
• READONLY command failed

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