redis/redis-py · critical · RedisClusterException

Redis Cluster cannot be connected. Please provide at least…

Error message

Redis Cluster cannot be connected. Please provide at least one reachable node: {str(exception)}

What it means

Raised as a RedisClusterException when none of the provided startup_nodes could be reached during initial topology discovery. The loop at cluster.py:2653-2708 tries each startup node, catches all exceptions, and if startup_nodes_reachable is still False after exhausting the list, raises this with the last exception chained (cluster.py:2773-2777). The message includes the underlying exception for diagnosis.

Solutions

1. Verify at least one node is reachable: telnet host port or redis-cli -h host -p ping.
2. Check the host and port values in the RedisCluster constructor for typos.
3. If using TLS, pass ssl=True and the correct ssl_* parameters, or remove them if not.
4. Ensure the Redis cluster containers/services are running (docker-compose ps, systemctl status redis).

Example fix

null

import socket
def is_reachable(host: str, port: int, timeout=2) -> bool:
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return True
    except OSError:
        return False

# Validate all startup nodes are reachable
for h, p in startup_nodes:
    assert is_reachable(h, p), f'Cannot reach {h}:{p}'

def startup_nodes_reachable(nodes: list) -> bool:
    import socket
    for h, p in nodes:
        try:
            with socket.create_connection((h, p), timeout=2):
                pass
        except OSError:
            return False
    return True

from redis.exceptions import RedisClusterException
try:
    client = RedisCluster(host, port)
except RedisClusterException as e:
    if 'cannot be connected' in str(e):
        # inspect underlying exception, fix network/config, then retry
        raise

When it happens

Trigger: Constructing RedisCluster with a host/port (or startup_nodes) where every node is unreachable: wrong host, wrong port, network partition, firewall, or all nodes are down. The last caught exception is embedded in the message.

Common situations: Typo in host or port, Redis cluster containers not started, network/firewall blocking the port, TLS mismatch (connecting plain to a TLS port), or DNS resolution failure.

Related errors

• Bad response from PING health check
• Cluster Node has no redis_connection
• Connection closed by server.
• Connection closed by server.
• Connection closed by server.

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

Appendix: source

Thrown at redis/cluster.py:2774

                            if tmp_slot.name != target_node.name:
                                disagreements.append(
                                    f"{tmp_slot.name} vs {target_node.name} on slot: {i}"
                                )

                                if len(disagreements) > 5:
                                    raise RedisClusterException(
                                        f"startup_nodes could not agree on a valid "
                                        f"slots cache: {', '.join(disagreements)}"
                                    )

                fully_covered = self.check_slots_coverage(tmp_slots)
                if fully_covered:
                    # Don't need to continue to the next startup node if all
                    # slots are covered
                    break

            if not startup_nodes_reachable:
                raise RedisClusterException(
                    f"Redis Cluster cannot be connected. Please provide at least "
                    f"one reachable node: {str(exception)}"
                ) from exception

            # Create Redis connections to all nodes
            self.create_redis_connections(list(tmp_nodes_cache.values()))

            # Check if the slots are not fully covered
            if not fully_covered and self._require_full_coverage:
                # Despite the requirement that the slots be covered, there
                # isn't a full coverage
                raise RedisClusterException(
                    f"All slots are not covered after query all startup_nodes. "
                    f"{len(tmp_slots)} of {REDIS_CLUSTER_HASH_SLOTS} "
                    f"covered..."
                )

            # Set the tmp variables to the real variables

View on GitHub (pinned to 6a6b581b48)