What causes "Unable to locate Redisson instance by name: " + jndiName" in redisson/redisson?

Decode the cause: NameNotFoundException → wrong name; CommunicationException → provider URL/connectivity; then fix accordingly.

redisson/redisson · error · CacheException

Unable to locate Redisson instance by name: " + jndiName

Error message

Unable to locate Redisson instance by name: " + jndiName

What it means

Thrown by JndiRedissonRegionFactory (hibernate-52 module) when context.lookup(jndiName) fails with a NamingException: no object is bound at the configured hibernate.cache.redisson.jndi_name, the JNDI provider cannot be reached, or the bound object cannot be returned as a RedissonClient. The NamingException is preserved as the cause and identifies which case applies.

Source

Thrown at redisson-hibernate/redisson-hibernate-52/src/main/java/org/redisson/hibernate/JndiRedissonRegionFactory.java:55

    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);
                }
            }
        }
    }

    @Override
    public void stop() {
    }

}

View on GitHub (pinned to 91188987c2)

Solutions

Decode the cause: NameNotFoundException → wrong name; CommunicationException → provider URL/connectivity; then fix accordingly.
Guarantee startup order: create Redisson.create(config) and rebind it in JNDI before the SessionFactory bean is constructed (e.g. @DependsOn / BeanFactoryPostProcessor in Spring).
Match the exact JNDI name including prefix (java:/ vs java:comp/env/) between binder and Hibernate config.
Supply required java.naming.* properties through the Hibernate properties so they reach the InitialContext.

Example fix

// before: client created after Hibernate starts
@Bean RedissonClient redisson() { return Redisson.create(config); }

// after: bind before SessionFactory and declare dependency
@Bean(destroyMethod = "shutdown") RedissonClient redisson() throws Exception {
    RedissonClient r = Redisson.create(config);
    new InitialContext().rebind("java:/redisson/RedissonClient", r);
    return r;
}
@Bean LocalContainerEntityManagerFactoryBean emf(@Autowired RedissonClient unused) { ... }

Defensive patterns

Strategy: validation

Validate before calling

try (InitialContext ctx = new InitialContext(jndiProps)) {
    Object o = ctx.lookup(jndiName);
    if (!(o instanceof RedissonClient)) throw new IllegalStateException("Not a RedissonClient at " + jndiName);
} catch (NamingException e) {
    throw new IllegalStateException("JNDI lookup failed for " + jndiName, e);
}

Type guard

private Optional<RedissonClient> lookupRedisson(String name) {
    try (InitialContext ctx = new InitialContext()) {
        return Optional.ofNullable(ctx.lookup(name))
            .filter(RedissonClient.class::isInstance)
            .map(RedissonClient.class::cast);
    } catch (NamingException e) {
        return Optional.empty();
    }
}

Try / catch

catch (CacheException e) {
    NamingException cause = (NamingException) e.getCause();
    if (cause instanceof NameNotFoundException) { /* correct the jndi_name value */ }
    else if (cause instanceof CommunicationException) { /* fix provider connectivity */ }
    else throw e;
}

Prevention

Initialize and bind the RedissonClient before the SessionFactory bean; declare the dependency.
Pre-probe the JNDI binding in a startup check.
Externalize the JNDI name per environment instead of hard-coding.

When it happens

Trigger: Hibernate 5.2+ startup with JndiRedissonRegionFactory where the jndi_name value does not exist in the JNDI tree (NameNotFoundException), the naming provider is unreachable (CommunicationException), or JNDI environment properties (java.naming.factory.initial / provider.url) are wrong so lookup targets the wrong registry.

Common situations: The component that creates and rebinds the RedissonClient runs after Hibernate initialization; deploying a WAR expecting java:comp/env/... names that require resource-ref mappings; local tests without any JNDI provider; environment-specific JNDI names hard-coded for one container but deployed to another.

Related errors

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