redisson/redisson · critical · CacheException

Unable to locate Redisson configuration

Error message

Unable to locate Redisson configuration

What it means

Thrown by RedissonRegionFactory.createRedissonClient when no Redisson configuration could be located. The factory first tries the path in 'hibernate.cache.redisson.file', then 'redisson.yaml' on the classpath (and as a file) when no path is given; if all attempts return null, Hibernate cache startup aborts with this CacheException.

Source

Thrown at redisson-hibernate/redisson-hibernate-72/src/main/java/org/redisson/hibernate/RedissonRegionFactory.java:113

    }

    protected RedissonClient createRedissonClient(StandardServiceRegistry registry, Map properties) {
        Config config = null;
        if (!properties.containsKey(REDISSON_CONFIG_PATH)) {
            config = loadConfig(RedissonRegionFactory.class.getClassLoader(), "redisson.json");
            if (config == null) {
                config = loadConfig(RedissonRegionFactory.class.getClassLoader(), "redisson.yaml");
            }
        } else {
            String configPath = ConfigurationHelper.getString(REDISSON_CONFIG_PATH, properties);
            config = loadConfig(RedissonRegionFactory.class.getClassLoader(), configPath);
            if (config == null) {
                config = loadConfig(configPath);
            }
        }
        
        if (config == null) {
            throw new CacheException("Unable to locate Redisson configuration");
        }

        return Redisson.create(config);
    }
    
    private Config loadConfig(String configPath) {
        try {
            return Config.fromYAML(new File(configPath));
        } catch (Exception e) {
            throw new CacheException("Can't parse default config", e);
        }
    }
    
    private Config loadConfig(ClassLoader classLoader, String fileName) {
        InputStream is = classLoader.getResourceAsStream(fileName);
        if (is != null) {
            try {
                return Config.fromYAML(is);

View on GitHub (pinned to 91188987c2)

Solutions

1. Add a valid redisson.yaml to src/main/resources (classpath root)
2. Or set hibernate.cache.redisson.file=/path/to/redisson.yaml (filesystem) or a classpath resource name
3. Verify the file is actually packaged (check the built JAR/WAR contents) and the property name has no typo

Example fix

# before: no redisson config anywhere
hibernate.cache.region.factory_class=org.redisson.hibernate.RedissonRegionFactory

# after: point at an explicit file
hibernate.cache.region.factory_class=org.redisson.hibernate.RedissonRegionFactory
hibernate.cache.redisson.file=redisson.yaml
# and add src/main/resources/redisson.yaml:
# singleServerConfig:
#   address: "redis://127.0.0.1:6379"

String path = properties.getProperty("hibernate.cache.redisson.file");
boolean classpathOk = RedissonRegionFactory.class.getClassLoader()
        .getResource("redisson.yaml") != null;
boolean fileOk = path != null && new File(path).isFile();
if (path == null && !classpathOk || path != null && !fileOk && !classpathOk) {
    throw new IllegalStateException("No Redisson config found: set hibernate.cache.redisson.file or add redisson.yaml to the classpath");
}

catch (CacheException e) during SessionFactory build and surface 'Redisson configuration missing' to deployment tooling; configuration problem, no retry value.

When it happens

Trigger: No hibernate.cache.redisson.file property set AND no redisson.yaml/redisson.json resource on the classpath; or hibernate.cache.redisson.file points to a path that exists neither on the classpath nor on the filesystem (both loadConfig overloads return null).

Common situations: New project using Redisson as Hibernate 2nd-level cache without shipping a config file; config file named differently (redisson-config.yaml) or placed in a directory not on the classpath; running tests where src/main/resources is not on the test classpath.

Related errors

• Unable to locate Redisson configuration
• Can't parse config
• Unable to locate Redisson configuration
• Can't parse config
• Unable to locate Redisson configuration

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