What causes "hibernate.cache.redisson.jndi_name property not set" in redisson/redisson?

Verify the node you pass is a master: filter by RedisClusterNode.isMaster() or Role.MASTER before calling APIs that resolve masters by address.

redisson/redisson · error · CacheException

hibernate.cache.redisson.jndi_name property not set

Error message

hibernate.cache.redisson.jndi_name property not set

What it means

Thrown by RedissonClusterConnection when clusterGetNodes() output does not contain a node whose host/port match the requested master's InetSocketAddress. The loop compares master.getHost()/getPort() to each RedisClusterNode and throws IllegalStateException if no match is found. Typically the caller passed a node (or host:port) that is not a known master in the current cluster topology view.

Source

Thrown at redisson-hibernate/redisson-hibernate-4/src/main/java/org/redisson/hibernate/JndiRedissonRegionFactory.java:45

/**
 * Hibernate Cache region factory based on Redisson. 
 * Uses Redisson instance located in JNDI.
 * 
 * @author Nikita Koksharov 
 *
 */
public class JndiRedissonRegionFactory extends RedissonRegionFactory {

    private static final long serialVersionUID = -4814502675083325567L;

    public static final String JNDI_NAME = CONFIG_PREFIX + "jndi_name";
    
    @Override
    protected RedissonClient createRedissonClient(Properties properties) {
        String jndiName = ConfigurationHelper.getString(JNDI_NAME, properties);
        if (jndiName == null) {
            throw new CacheException(JNDI_NAME + " property not set");
        }
        
        Properties jndiProperties = JndiServiceImpl.extractJndiProperties(properties);
        InitialContext context = null;
        try {
            context = new InitialContext(jndiProperties);
            return (RedissonClient) context.lookup(jndiName);
        } catch (NamingException e) {
            throw new CacheException("Unable to locate Redisson instance by name: " + jndiName, e);
        } finally {
            if (context != null) {
                try {
                    context.close();
                } catch (NamingException e) {
                    throw new CacheException("Unable to close JNDI context", e);
                }
            }
        }

View on GitHub (pinned to 91188987c2)

Solutions

Verify the node you pass is a master: filter by RedisClusterNode.isMaster() or Role.MASTER before calling APIs that resolve masters by address.
Re-fetch the topology via clusterGetNodes() right before the call instead of caching node objects across failovers.
Check the host:port exactly matches what the cluster reports (cluster nodes output), including port and any announced-ip/announce-port NAT settings.
Confirm Redisson was configured with ClusterServersConfig and all seed nodes are reachable, so clusterGetNodes() returns the real topology.

Example fix

// before
RedisClusterNode node = clusterConnection.clusterGetNodes().iterator().next();
Collection<RedisClusterNode> slaves = clusterConnection.clusterGetSlaves(node); // may throw if node is a replica

// after
RedisClusterNode master = clusterConnection.clusterGetNodes().stream()
        .filter(RedisClusterNode::isMaster)
        .findFirst()
        .orElseThrow(() -> new IllegalStateException("no master in topology"));
Collection<RedisClusterNode> slaves = clusterConnection.clusterGetSlaves(master);

Defensive patterns

Strategy: validation

Validate before calling

// before calling cluster master-resolution APIs
RedisClusterNode master = clusterConn.clusterGetNodes().stream()
        .filter(n -> n.isMaster()
                && n.getHost().equals(requested.getHost())
                && n.getPort() == requested.getPort())
        .findFirst().orElse(null);
if (master == null) {
    // refresh topology or fail with clear message; do not call the API
}

Try / catch

catch (IllegalStateException e) when message starts with 'Unable to find master node': treat as stale/incorrect topology — refresh clusterGetNodes() and retry once, else surface configuration error.

Prevention

Always fetch node topology fresh via clusterGetNodes() before master-address-based calls; never cache RedisClusterNode across failovers.
Filter nodes by Role.MASTER before using them as master arguments.
Verify the Redisson config lists all cluster seed nodes with correct ports so topology discovery is accurate.
In NAT/docker environments, configure announced IPs so reported host:port match what you compare against.

When it happens

Trigger: Calling cluster-get-slaves style operations on RedissonClusterConnection (e.g. clusterGetSlaves(node) / clusterGetMasterSlaveByMasterAddr or any API that internally resolves a master by address) with a RedisClusterNode or host:port that is not a master in the cluster (a replica address, a stale/removed node, or a wrong port). Also occurs if the cluster topology changed (reshard/failover) between fetching node info and the lookup, or if the cluster connection is actually pointed at a non-cluster deployment.

Common situations: Passing a replica node where a master is required; using a stale node list after failover; wrong port in the Spring node configuration (e.g. 6379 vs 7000); connecting a cluster connection factory to a single-instance Redis; DNS/NAT remapping so reported host differs from configured host.

Related errors

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