redisson/redisson · error · IllegalStateException

Unable to find master node: {}

Error message

Unable to find master node: {}

What it means

RedissonClusterConnection resolves slave replicas by matching the configured master host/port against the cluster node list obtained via clusterGetNodes(). If no node in the topology view matches the master's host and port, the connection's view of the cluster is stale or misconfigured, and it throws IllegalStateException naming the master it could not find.

Source

Thrown at redisson-spring/redisson-spring-data/redisson-spring-data-22/src/main/java/org/redisson/spring/data/connection/RedissonClusterConnection.java:85

                new ObjectDecoder(new RedisClusterNodeDecoder(executorService.getServiceManager())));
        return read(null, StringCodec.INSTANCE, cluster);
    }

    @Override
    public Collection<RedisClusterNode> clusterGetSlaves(RedisClusterNode master) {
        Iterable<RedisClusterNode> res = clusterGetNodes();
        RedisClusterNode masterNode = null;
        for (Iterator<RedisClusterNode> iterator = res.iterator(); iterator.hasNext();) {
            RedisClusterNode redisClusterNode = iterator.next();
            if (master.getHost().equals(redisClusterNode.getHost()) 
                    && master.getPort().equals(redisClusterNode.getPort())) {
                masterNode = redisClusterNode;
                break;
            }
        }
        
        if (masterNode == null) {
            throw new IllegalStateException("Unable to find master node: " + master);
        }
        
        for (Iterator<RedisClusterNode> iterator = res.iterator(); iterator.hasNext();) {
            RedisClusterNode redisClusterNode = iterator.next();
            if (redisClusterNode.getMasterId() == null 
                    || !redisClusterNode.getMasterId().equals(masterNode.getId())) {
                iterator.remove();
            }
        }
        return (Collection<RedisClusterNode>) res;
    }

    @Override
    public Map<RedisClusterNode, Collection<RedisClusterNode>> clusterGetMasterSlaveMap() {
        Iterable<RedisClusterNode> res = clusterGetNodes();
        
        Set<RedisClusterNode> masters = new HashSet<RedisClusterNode>();
        for (Iterator<RedisClusterNode> iterator = res.iterator(); iterator.hasNext();) {

View on GitHub (pinned to 91188987c2)

Solutions

  1. Make the configured master address match what the cluster announces (use the same hostnames/IPs the nodes advertise in CLUSTER NODES)
  2. Trigger a topology refresh / recreate the Redisson client after a failover so clusterGetNodes() returns current data
  3. In containerized environments, ensure announce-ip/announce-port (or Docker NAT settings) are consistent across all nodes

Example fix

// before
config.useClusterServers()
      .addNodeAddress("redis://10.0.0.5:6379"); // cluster announces redis-master:6379

// after
config.useClusterServers()
      .addNodeAddress("redis://redis-master:6379"); // matches announced host:port
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check that the configured master appears in the topology before asking for replicas:
RedisClusterNode match = StreamSupport.stream(clusterGetNodes().spliterator(), false)
        .filter(n -> n.getHost().equals(master.getHost()) && n.getPort() == master.getPort())
        .findFirst().orElse(null);
if (match == null) { /* refresh topology / re-create client */ }

Try / catch

try {
    Collection<RedisClusterNode> replicas = connection.clusterGetReplicas(master);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to find master node")) {
        // topology drift: refresh cluster topology or rebuild RedissonClient, then retry once
    }
}

Prevention

When it happens

Trigger: Calling clusterGetReplicas(master) / getClusterClusterConnection slave resolution when the cluster topology changed (failover, resharding, node restart with new address) or when the Config's master address does not exactly match a node's host/port in CLUSTER NODES output (e.g. DNS name vs IP mismatch).

Common situations: Cluster failover just happened and the client holds an old topology; connecting through a proxy/Docker NAT where the advertised host differs from the configured address; mixed use of hostnames and IPs between config and cluster announcements.

Related errors

AI-assisted analysis of redisson/redisson@91188987c2 (2026-08-14). Data as JSON: /api/errors/c23823d4b06114f0. Report an issue: GitHub.