{"record":{"id":"2989253f0af32611","repo":"redis/redis-py","slug":"rediscluster-requires-at-least-one-node-to-discove-298925","errorCode":null,"errorMessage":"RedisCluster requires at least one node to discover the cluster. Please provide one of the followings:\n1. host and port, for example:\n RedisCluster(host='localhost', port=6379)\n2. list of startup nodes, for example:\n RedisCluster(startup_nodes=[ClusterNode('localhost', 6379),\n ClusterNode('localhost', 6378)])","messagePattern":"RedisCluster requires at least one node to discover the cluster\\. Please provide one of the followings:\n1\\. host and port, for example:\n RedisCluster\\(host='localhost', port=6379\\)\n2\\. list of startup nodes, for example:\n RedisCluster\\(startup_nodes=\\[ClusterNode\\('localhost', 6379\\),\n ClusterNode\\('localhost', 6378\\)\\]\\)","errorType":"exception","errorClass":"RedisClusterException","httpStatus":null,"severity":"error","filePath":"redis/cluster.py","lineNumber":853,"sourceCode":"            if \"path\" in url_options:\n                raise RedisClusterException(\n                    \"RedisCluster does not currently support Unix Domain \"\n                    \"Socket connections\"\n                )\n            if \"db\" in url_options and url_options[\"db\"] != 0:\n                # Argument 'db' is not possible to use in cluster mode\n                raise RedisClusterException(\n                    \"A ``db`` querystring option can only be 0 in cluster mode\"\n                )\n            kwargs.update(url_options)\n            host = kwargs.get(\"host\")\n            port = kwargs.get(\"port\", port)\n            startup_nodes.append(ClusterNode(host, port))\n        elif host is not None and port is not None:\n            startup_nodes.append(ClusterNode(host, port))\n        elif len(startup_nodes) == 0:\n            # No startup node was provided\n            raise RedisClusterException(\n                \"RedisCluster requires at least one node to discover the \"\n                \"cluster. Please provide one of the followings:\\n\"\n                \"1. host and port, for example:\\n\"\n                \" RedisCluster(host='localhost', port=6379)\\n\"\n                \"2. list of startup nodes, for example:\\n\"\n                \" RedisCluster(startup_nodes=[ClusterNode('localhost', 6379),\"\n                \" ClusterNode('localhost', 6378)])\"\n            )\n        # Update the connection arguments\n        # Whenever a new connection is established, RedisCluster's on_connect\n        # method should be run\n        # If the user passed on_connect function we'll save it and run it\n        # inside the RedisCluster.on_connect() function\n        self.user_on_connect_func = kwargs.pop(\"redis_connect_func\", None)\n        kwargs.update({\"redis_connect_func\": self.on_connect})\n        kwargs = cleanup_kwargs(**kwargs)\n        if retry:\n            self.retry = retry","sourceCodeStart":835,"sourceCodeEnd":871,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/cluster.py#L835-L871","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nclient = RedisCluster()  # RedisClusterException\n\n// after\nclient = RedisCluster(host='localhost', port=7000)\n# or\nfrom redis.cluster import ClusterNode\nclient = RedisCluster(startup_nodes=[ClusterNode('localhost', 7000)])","handlingStrategy":"validation","validationCode":"if not (host and port) and not startup_nodes and not url:\n    raise ValueError('Provide host+port, startup_nodes, or url to RedisCluster')\nclient = 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)","typeGuard":"def has_cluster_seed(host, port, startup_nodes, url) -> bool:\n    return bool(url) or bool(host and port) or bool(startup_nodes)","tryCatchPattern":"from redis.cluster import RedisClusterException\ntry:\n    client = RedisCluster(host=host, port=port)\nexcept RedisClusterException:\n    client = RedisCluster(host='localhost', port=7000)  # safe default","preventionTips":["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)."],"tags":["cluster","config","api-misuse","startup"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}