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 JndiRedissonRegionNativeFactory (hibernate-5 native module) when context.lookup(jndiName) raises a NamingException — the JNDI name resolved from hibernate.cache.redisson.jndi_name does not yield an object. The original NamingException is attached as the cause, so its type (NameNotFoundException vs CommunicationException vs ClassCastException-free lookup failure) tells you whether the name is missing, the provider is unreachable, or the bound object is not a RedissonClient.

Source

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

    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

  1. Inspect the cause: NameNotFoundException = fix the binding name; CommunicationException = fix JNDI provider connectivity/URL properties.
  2. Bind the RedissonClient into JNDI before Hibernate starts, e.g. new InitialContext().rebind("java:/redisson/RedissonClient", redisson) in a bean that initializes first.
  3. Correct the hibernate.cache.redisson.jndi_name value to match the exact name used when binding (including the java: prefix used by your container).
  4. If the JNDI environment properties are needed, pass them as hibernate.cache.redisson.* / java.naming.* entries so JndiServiceImpl.extractJndiProperties picks them up.

Example fix

// before: RedissonClient never bound
// hibernate.cache.redisson.jndi_name = java:/redisson/RedissonClient

// after: bind the client before the SessionFactory is created
RedissonClient redisson = Redisson.create(config);
new InitialContext().rebind("java:/redisson/RedissonClient", redisson);
// then build the SessionFactory
Defensive patterns

Strategy: validation

Validate before calling

// Fail fast before Hibernate starts if the binding is absent
InitialContext ctx = new InitialContext(jndiProps);
Object bound;
try {
    bound = ctx.lookup(jndiName);
} finally {
    try { ctx.close(); } catch (NamingException ignore) {}
}
if (!(bound instanceof RedissonClient)) {
    throw new IllegalStateException(jndiName + " does not hold a RedissonClient");
}

Type guard

private boolean isRedissonClientBound(String name, Properties jndiProps) {
    try (InitialContext ctx = new InitialContext(jndiProps)) {
        return ctx.lookup(name) instanceof RedissonClient;
    } catch (NamingException e) {
        return false;
    }
}

Try / catch

catch (CacheException e) {
    if (e.getCause() instanceof NameNotFoundException) { /* fix binding name */ }
    else if (e.getCause() instanceof CommunicationException) { /* fix provider URL / network */ }
    else throw e;
}

Prevention

When it happens

Trigger: Hibernate startup with JndiRedissonRegionNativeFactory where jndi_name points to a name not bound in JNDI; the JNDI provider is unreachable (bad java.naming.provider.url); or the object bound at that name is not a RedissonClient (lookup succeeds but cast/reference resolution fails).

Common situations: The RedissonClient was never bound (the Spring bean / app-server resource creating and rebinding it was not initialized before Hibernate started); environment differences between dev (local JNDI) and prod (app-server JNDI tree); wrong prefix such as java:comp/env/redisson vs java:/redisson; JNDI provider properties (java.naming.factory.initial, provider.url) missing so a default (often RMI) context is used.

Related errors

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