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

JndiRedissonRegionFactory (and its Native variant) builds its RedissonClient by looking one up in JNDI instead of creating one from a config file. The required property hibernate.cache.redisson.jndi_name is read with ConfigurationHelper.getString; when absent, CacheException('<key> property not set') is thrown at cache startup.

Source

Thrown at redisson-hibernate/redisson-hibernate-6/src/main/java/org/redisson/hibernate/JndiRedissonRegionNativeFactory.java:44

/**
 * 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(StandardServiceRegistry registry, Map properties) {
        String jndiName = ConfigurationHelper.getString(JNDI_NAME, properties);
        if (jndiName == null) {
            throw new CacheException(JNDI_NAME + " property not set");
        }

        try {
            return (RedissonClient) registry.getService(JndiService.class).locate(jndiName);
        } catch (JndiException e) {
            throw new CacheException(e);
        }
    }

    @Override
    protected void releaseFromUse() {
    }

}

View on GitHub (pinned to 91188987c2)

Solutions

  1. Add <property name="hibernate.cache.redisson.jndi_name" value="redisson"/> (or your binding) to persistence.xml / hibernate.cfg.xml.
  2. Bind a RedissonClient instance into the app server's JNDI tree under exactly that name (WildFly: java:global/redisson via a resource adapter or @Produces; Tomcat: Resource in context.xml).
  3. Verify the binding with a JNDI lookup before starting Hibernate; a wrong name later surfaces as CacheException(JndiException).
  4. For non-container environments use RedissonRegionFactory with redisson.yaml instead of the JNDI variant.

Example fix

// before
<property name="hibernate.cache.region.factory_class"
          value="org.redisson.hibernate.JndiRedissonRegionFactory"/>
<!-- no jndi_name -> CacheException -->

// after
<property name="hibernate.cache.region.factory_class"
          value="org.redisson.hibernate.JndiRedissonRegionFactory"/>
<property name="hibernate.cache.redisson.jndi_name" value="redisson"/>
Defensive patterns

Strategy: validation

Validate before calling

// Verify the property and binding before Hibernate boots
String jndiName = (String) props.get("hibernate.cache.redisson.jndi_name");
if (jndiName == null || jndiName.isBlank()) {
    throw new IllegalStateException("hibernate.cache.redisson.jndi_name is required for JndiRedissonRegionFactory");
}
new InitialContext().lookup(jndiName); // throws NameNotFoundException early if unbound

Try / catch

try {
    sessionFactory = metadata.buildSessionFactory();
} catch (CacheException e) {
    if (e.getMessage() != null && e.getMessage().contains("jndi_name property not set")) {
        throw new BootstrapException("Set hibernate.cache.redisson.jndi_name and bind a RedissonClient in JNDI", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Setting cache.region_factory to JndiRedissonRegionFactory (or JndiRedissonRegionNativeFactory) without defining the hibernate.cache.redisson.jndi_name property in the Hibernate configuration.

Common situations: Migrating an app to an app-server-managed Redisson but forgetting the jndi_name property; property name typos (jndiName vs jndi_name); the name present in one persistence unit but not another; running unit tests outside the container where no JNDI exists.

Related errors

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