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 in `RedisCluster.__init__` when no bootstrap node can be determined. The cluster client needs at least one reachable node to perform slot/topology discovery; if neither `url`, nor `host`+`port`, nor a non-empty `startup_nodes` list is supplied, it cannot begin discovery and raises RedisClusterException listing the supported construction 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 da03cdc7e8)

Solutions

  1. Provide host and port: `RedisCluster(host='localhost', port=7000)`.
  2. Or supply startup_nodes: `RedisCluster(startup_nodes=[ClusterNode('h', 7000), ClusterNode('h', 7001)])`.
  3. Or use `RedisCluster.from_url('redis://host:7000')`.
  4. Verify env vars/config loading actually populates the values before constructing.

Example fix

# before
rc = RedisCluster()  # raises: requires at least one node

# after
rc = RedisCluster(host='localhost', port=7000)
Defensive patterns

Strategy: validation

Validate before calling

def make_cluster(host=None, port=None, startup_nodes=None, url=None):
    if not (url or (host and port) or startup_nodes):
        raise ValueError('Provide host+port, startup_nodes, or url')
    return RedisCluster(host=host, port=port, startup_nodes=startup_nodes, url=url)

Type guard

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

Prevention

When it happens

Trigger: Calling `RedisCluster()` with no arguments; passing `startup_nodes=[]` (the default) without host/port; providing only host without port or vice-versa; supplying a malformed URL that parses to neither host nor startup_nodes.

Common situations: Missing/typo'd configuration; environment variables for host/port not loaded; constructing from a config dict where both host and startup_nodes ended up None.

Related errors

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