redis/redis-py · error · RedisClusterException

RedisCluster requires at least one node to discover the clus

Error message

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

What it means

Raised by RedisCluster.__init__ (redis/asyncio/cluster.py:471) when neither (host and port) nor startup_nodes is provided. The cluster client needs at least one bootstrap node to run CLUSTER SLOTS/NODES and build the slot map; with no entry point it cannot discover topology. The message lists the two accepted construction forms.

Source

Thrown at redis/asyncio/cluster.py:471

        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)

        kwargs: Dict[str, Any] = {
            "max_connections": max_connections,
            "connection_class": Connection,
            # Client related kwargs
            "credential_provider": credential_provider,
            "username": username,
            "password": password,
            "client_name": client_name,
            "driver_info": computed_driver_info,

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Provide host and port: RedisCluster(host='localhost', port=16379).
2. Provide startup_nodes: RedisCluster(startup_nodes=[ClusterNode('h1', 6379), ClusterNode('h2', 6379)]).
3. Use RedisCluster.from_url('redis://host:16379/0') to parse the endpoint from a URL.
4. Validate that host AND port are both set (truthiness), not just one.

Example fix

// before
c = RedisCluster()  # raises
// after
c = RedisCluster(host='localhost', port=16379)
# or
c = RedisCluster.from_url('redis://localhost:16379/0')

if not ((host and port) or startup_nodes):
    raise ValueError('Provide host+port or startup_nodes (or use from_url)')
c = RedisCluster(host=host, port=port, startup_nodes=startup_nodes)

When it happens

Trigger: Calling RedisCluster() with no arguments, or passing only one of host/port, or passing an empty startup_nodes list. The guard is `if (not host or not port) and not startup_nodes:`.

Common situations: Loading cluster config from environment where HOST/PORT env vars are unset; misconfigured URL parsing; constructing from a dict that omitted the node specifier.

Related errors

• Argument 'db' must be 0 or None in cluster mode
• Unix domain socket is not supported in cluster mode
• 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/d8741669070a3ace.json. Report an issue: GitHub.