redis/redis-py · critical · RedisClusterException

Redis Cluster cannot be connected. Please provide at least o

Error message

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

What it means

Raised at the end of initialize() when no startup node could be reached at all. The client tried every seed node, each attempt threw (connection refused, timeout, DNS failure, auth error), and the last exception is wrapped with this message. Without a single reachable node the client cannot learn the cluster topology, so construction fails.

Source

Thrown at redis/asyncio/cluster.py:2371

                                )

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

                # Validate if all slots are covered or if we should try next startup node
                fully_covered = True
                for i in range(REDIS_CLUSTER_HASH_SLOTS):
                    if i not in tmp_slots:
                        fully_covered = False
                        break
                if fully_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

            # 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
            self.set_nodes(self.nodes_cache, tmp_nodes_cache, remove_old=True)
            # tmp_slots was built from CLUSTER SLOTS responses and can contain
            # newly-created ClusterNode objects for nodes we already know about.

View on GitHub (pinned to da03cdc7e8)

Solutions

Verify reachability independently: telnet/nc <host> <port> or redis-cli -h <host> -p <port> PING.
Correct the scheme for TLS endpoints (rediss://) and supply the right password/credential_provider.
Refresh the startup_nodes list with currently-live nodes and check security groups/firewall rules.

Example fix

// before
rc = RedisCluster(host='redis.internal', port=6379)  # unreachable

// after
# verify connectivity first
# redis-cli -h redis.internal -p 6379 PING  -> PONG
rc = RedisCluster(host='redis.internal', port=6379)

Defensive patterns

Strategy: validation

Validate before calling

import socket

def assert_reachable(host, port, timeout=3):
    try:
        with socket.create_connection((host, port), timeout=timeout):
            pass
    except OSError as e:
        raise RuntimeError(f'Cannot reach {host}:{port}: {e}') from e

# before constructing the client
assert_reachable(host, port)
rc = RedisCluster(host=host, port=port)

Type guard

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

Try / catch

from redis.cluster import RedisClusterException

try:
    rc = RedisCluster.from_url(url)
except RedisClusterException as e:
    if 'cannot be connected' in str(e):
        # log and surface actionable guidance
        raise RuntimeError('All seed nodes unreachable — check host/port/firewall/TLS/auth') from e
    raise

Prevention

Preflight-check TCP reachability to each seed node before constructing the client.
Match the URL scheme to the endpoint (rediss:// for TLS).
Keep the startup_nodes list current and validate credentials/ACLs in CI.

When it happens

Trigger: Wrong host/port in the URL; firewall/network ACL blocking the Redis port; all seed nodes down; TLS mismatch (redis:// vs rediss://); authentication failure (wrong password / missing ACL); DNS not resolving the cluster endpoint.

Common situations: Connecting from outside a VPC/security group without the port opened; stale startup_nodes list after a cluster migration; AUTH/RequirePass misconfiguration; using plain redis:// against a TLS-only endpoint.

Related errors

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