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 followings:
1. host and port, for example:
 RedisCluster(host='localhost', port=6379)
2. list of startup nodes, for example:
 RedisCluster(startup_nodes=[ClusterNode('localhost', 6379),
 ClusterNode('localhost', 6378)])

What it means

Raised by RedisCluster.__init__ when no startup node can be determined: url is None, host/port not both provided, and startup_nodes is empty. The cluster client needs at least one seed node to run CLUSTER NODES/CLUSTER SLOTS and discover the topology, so construction fails with an explanatory message listing the supported forms.

Source

Thrown at redis/cluster.py:853

            if "path" in url_options:
                raise RedisClusterException(
                    "RedisCluster does not currently support Unix Domain "
                    "Socket connections"
                )
            if "db" in url_options and url_options["db"] != 0:
                # Argument 'db' is not possible to use in cluster mode
                raise RedisClusterException(
                    "A ``db`` querystring option can only be 0 in cluster mode"
                )
            kwargs.update(url_options)
            host = kwargs.get("host")
            port = kwargs.get("port", port)
            startup_nodes.append(ClusterNode(host, port))
        elif host is not None and port is not None:
            startup_nodes.append(ClusterNode(host, port))
        elif len(startup_nodes) == 0:
            # No startup node was provided
            raise RedisClusterException(
                "RedisCluster requires at least one node to discover the "
                "cluster. Please provide one of the followings:\n"
                "1. host and port, for example:\n"
                " RedisCluster(host='localhost', port=6379)\n"
                "2. list of startup nodes, for example:\n"
                " RedisCluster(startup_nodes=[ClusterNode('localhost', 6379),"
                " ClusterNode('localhost', 6378)])"
            )
        # Update the connection arguments
        # Whenever a new connection is established, RedisCluster's on_connect
        # method should be run
        # If the user passed on_connect function we'll save it and run it
        # inside the RedisCluster.on_connect() function
        self.user_on_connect_func = kwargs.pop("redis_connect_func", None)
        kwargs.update({"redis_connect_func": self.on_connect})
        kwargs = cleanup_kwargs(**kwargs)
        if retry:
            self.retry = retry

View on GitHub (pinned to 6a6b581b48)

Solutions

Provide host and port: RedisCluster(host='localhost', port=7000).
Or provide startup_nodes=[ClusterNode('host', port), ...].
Or provide url='redis://host:port'.
If using env vars, guard that both host and port are set before constructing.

Example fix

// before
client = RedisCluster()  # RedisClusterException

// after
client = RedisCluster(host='localhost', port=7000)
# or
from redis.cluster import ClusterNode
client = RedisCluster(startup_nodes=[ClusterNode('localhost', 7000)])

Defensive patterns

Strategy: validation

Validate before calling

if not (host and port) and not startup_nodes and not url:
    raise ValueError('Provide host+port, startup_nodes, or url to RedisCluster')
client = RedisCluster(host=host, port=port, startup_nodes=startup_nodes, url=url) if url else RedisCluster(host=host, port=port) if host and port else RedisCluster(startup_nodes=startup_nodes)

Type guard

def has_cluster_seed(host, port, startup_nodes, url) -> bool:
    return bool(url) or bool(host and port) or bool(startup_nodes)

Try / catch

from redis.cluster import RedisClusterException
try:
    client = RedisCluster(host=host, port=port)
except RedisClusterException:
    client = RedisCluster(host='localhost', port=7000)  # safe default

Prevention

Always pass an explicit host+port, startup_nodes, or url.
Validate required env vars are set before constructing.
Use the correct kwarg name (startup_nodes, not nodes).

When it happens

Trigger: RedisCluster() with no arguments; passing only host without port (or vice versa); passing startup_nodes=[]; passing url=None explicitly while omitting the others. The final elif at cluster.py:851 catches all empty cases.

Common situations: Misconfigured environment variables (REDIS_HOST set but REDIS_PORT blank); wrong kwarg name (e.g. nodes= instead of startup_nodes=); refactoring that accidentally drops the host/port arguments.

Related errors

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