{"record":{"id":"48d23f2d8e8cbae5","repo":"redisson/redisson","slug":"unable-to-locate-redisson-instance-by-name-jndi-48d23f","errorCode":null,"errorMessage":"Unable to locate Redisson instance by name: ${jndiName}","messagePattern":"Unable to locate Redisson instance by name: (.+?)","errorType":"exception","errorClass":"CacheException","httpStatus":null,"severity":"error","filePath":"redisson-hibernate/redisson-hibernate-5/src/main/java/org/redisson/hibernate/JndiRedissonRegionNativeFactory.java","lineNumber":53,"sourceCode":"\n    private static final long serialVersionUID = -4814502675083325567L;\n\n    public static final String JNDI_NAME = CONFIG_PREFIX + \"jndi_name\";\n    \n    @Override\n    protected RedissonClient createRedissonClient(Properties properties) {\n        String jndiName = ConfigurationHelper.getString(JNDI_NAME, properties);\n        if (jndiName == null) {\n            throw new CacheException(JNDI_NAME + \" property not set\");\n        }\n        \n        Properties jndiProperties = JndiServiceImpl.extractJndiProperties(properties);\n        InitialContext context = null;\n        try {\n            context = new InitialContext(jndiProperties);\n            return (RedissonClient) context.lookup(jndiName);\n        } catch (NamingException e) {\n            throw new CacheException(\"Unable to locate Redisson instance by name: \" + jndiName, e);\n        } finally {\n            if (context != null) {\n                try {\n                    context.close();\n                } catch (NamingException e) {\n                    throw new CacheException(\"Unable to close JNDI context\", e);\n                }\n            }\n        }\n    }\n\n    @Override\n    public void stop() {\n    }\n\n}\n","sourceCodeStart":35,"sourceCodeEnd":70,"githubUrl":"https://github.com/redisson/redisson/blob/91188987c2a9023e7fedabff758681ad9b107f25/redisson-hibernate/redisson-hibernate-5/src/main/java/org/redisson/hibernate/JndiRedissonRegionNativeFactory.java#L35-L70","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect the cause: NameNotFoundException = fix the binding name; CommunicationException = fix JNDI provider connectivity/URL properties.","Bind the RedissonClient into JNDI before Hibernate starts, e.g. new InitialContext().rebind(\"java:/redisson/RedissonClient\", redisson) in a bean that initializes first.","Correct the hibernate.cache.redisson.jndi_name value to match the exact name used when binding (including the java: prefix used by your container).","If the JNDI environment properties are needed, pass them as hibernate.cache.redisson.* / java.naming.* entries so JndiServiceImpl.extractJndiProperties picks them up."],"exampleFix":"// before: RedissonClient never bound\n// hibernate.cache.redisson.jndi_name = java:/redisson/RedissonClient\n\n// after: bind the client before the SessionFactory is created\nRedissonClient redisson = Redisson.create(config);\nnew InitialContext().rebind(\"java:/redisson/RedissonClient\", redisson);\n// then build the SessionFactory","handlingStrategy":"validation","validationCode":"// Fail fast before Hibernate starts if the binding is absent\nInitialContext ctx = new InitialContext(jndiProps);\nObject bound;\ntry {\n    bound = ctx.lookup(jndiName);\n} finally {\n    try { ctx.close(); } catch (NamingException ignore) {}\n}\nif (!(bound instanceof RedissonClient)) {\n    throw new IllegalStateException(jndiName + \" does not hold a RedissonClient\");\n}","typeGuard":"private boolean isRedissonClientBound(String name, Properties jndiProps) {\n    try (InitialContext ctx = new InitialContext(jndiProps)) {\n        return ctx.lookup(name) instanceof RedissonClient;\n    } catch (NamingException e) {\n        return false;\n    }\n}","tryCatchPattern":"catch (CacheException e) {\n    if (e.getCause() instanceof NameNotFoundException) { /* fix binding name */ }\n    else if (e.getCause() instanceof CommunicationException) { /* fix provider URL / network */ }\n    else throw e;\n}","preventionTips":["Bind the RedissonClient in an eagerly-initialized bean; declare SessionFactory dependency on it.","Pre-lookup the JNDI name in a startup probe before Hibernate builds.","Use environment variables for the JNDI name to avoid per-environment hard-coding."],"tags":["jndi","hibernate","redisson","lookup","startup"],"backgroundTag":null,"analyzedSha":"91188987c2a9023e7fedabff758681ad9b107f25","analyzedAt":"2026-08-14T11:39:42.619Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}