redisson/redisson · critical · CacheException

hibernate.cache.redisson.jndi_name property not set

Error message

hibernate.cache.redisson.jndi_name property not set

What it means

Thrown by JndiRedissonRegionNativeFactory (Hibernate 5.3 module, RMapCacheNative-backed regions) when the required hibernate.cache.redisson.jndi_name property is missing from the Hibernate configuration. Like its non-native twin (error 54) the factory fetches a pre-built RedissonClient from JNDI; with the property absent, ConfigurationHelper.getString returns null and startup fails fast with this CacheException before any JNDI work is attempted.

Source

Thrown at redisson-hibernate/redisson-hibernate-53/src/main/java/org/redisson/hibernate/JndiRedissonRegionNativeFactory.java:45

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

    private static final long serialVersionUID = -4814502675083325567L;

    public static final String JNDI_NAME = CONFIG_PREFIX + "jndi_name";
    
    @Override
    protected RedissonClient createRedissonClient(Map 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

  1. Add hibernate.cache.redisson.jndi_name=<name> with the exact underscore spelling to the same Hibernate configuration.
  2. Double-check the value is the name the container actually binds the RedissonClient to.
  3. If file-based config was intended, use RedissonRegionNativeFactory with redisson.yaml instead of the JNDI variant.

Example fix

# before
hibernate.cache.region_factory_class=org.redisson.hibernate.JndiRedissonRegionNativeFactory

# after
hibernate.cache.region_factory_class=org.redisson.hibernate.JndiRedissonRegionNativeFactory
hibernate.cache.redisson.jndi_name=java:jboss/redisson
Defensive patterns

Strategy: validation

Validate before calling

boolean nativeJndiConfigValid(java.util.Properties p) {
    return "org.redisson.hibernate.JndiRedissonRegionNativeFactory".equals(
               p.getProperty("hibernate.cache.region_factory_class"))
        == (p.getProperty("hibernate.cache.redisson.jndi_name") != null);
}

Try / catch

try {
    sessionFactory = cfg.buildSessionFactory();
} catch (CacheException e) {
    if (e.getMessage() != null && e.getMessage().endsWith("jndi_name property not set")) {
        // JNDI native factory selected but no name supplied — add the property
    }
    throw e;
}

Prevention

When it happens

Trigger: Configuring hibernate.cache.region_factory_class=org.redisson.hibernate.JndiRedissonRegionNativeFactory without hibernate.cache.redisson.jndi_name, or with a misspelled key such as hibernate.cache.redisson.jndi-name.

Common situations: Adopting the native factory for Redis-side eviction but reusing properties written for the yaml-based RedissonRegionFactory; config split across files where the JNDI entry is forgotten in one profile.

Related errors

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