redisson/redisson · error · IllegalArgumentException

.expiration.max_idle_time setting can't be non-zero

Error message

.expiration.max_idle_time setting can't be non-zero

What it means

Thrown by RedissonRegionNativeFactory.start (hibernate-5 native module) at startup when any cache property ending with the max-idle-time suffix (e.g. hibernate.cache.redisson.<region>.expiration.max_idle_time) is greater than 0. Native regions use Redis-native TTL/eviction, so per-region idle eviction configured client-side is rejected with IllegalArgumentException. (As with max_entries, the 'can't be non-zero' wording really means 'must not be positive'.)

Source

Thrown at redisson-hibernate/redisson-hibernate-5/src/main/java/org/redisson/hibernate/RedissonRegionNativeFactory.java:51

 */
public class RedissonRegionNativeFactory extends RedissonRegionFactory {

    private static final long serialVersionUID = 4889779229712681692L;

    @Override
    public void start(SessionFactoryOptions settings, Properties properties) throws CacheException {
        Set<Map.Entry<Object, Object>> entrySet = properties.entrySet();
        for (Map.Entry<Object, Object> entry : entrySet) {
            if (entry.getKey().toString().endsWith(RedissonRegionFactory.MAX_ENTRIES_SUFFIX)) {
                Integer value = Integer.valueOf(entry.getValue().toString());
                if (value > 0) {
                    throw new IllegalArgumentException(".eviction.max_entries setting can't be non-zero");
                }
            }
            if (entry.getKey().toString().endsWith(RedissonRegionFactory.MAX_IDLE_SUFFIX)) {
                Integer value = Integer.valueOf(entry.getValue().toString());
                if (value > 0) {
                    throw new IllegalArgumentException(".expiration.max_idle_time setting can't be non-zero");
                }
            }
        }
        super.start(settings, properties);
    }

    @Override
    protected RMapCache<Object, Object> getCache(String regionName, Properties properties, String defaultKey) {
        RMapCacheNative<Object, Object> cache = redisson.getMapCacheNative(regionName);
        return new MapCacheNativeWrapper<>(cache);
    }
    
}

View on GitHub (pinned to 91188987c2)

Solutions

1. Delete the hibernate.cache.redisson.<region>.expiration.max_idle_time entries (or set to 0) when using the native factory.
2. Rely on Redis server-side expiration policy (maxmemory-policy, key TTL) for idle-based eviction.
3. Switch to RedissonRegionFactory if per-region max_idle_time semantics are required.
4. Audit all *.expiration.max_idle_time keys across your configuration files — one positive value aborts startup.

Example fix

# before
hibernate.cache.region.factory_class=org.redisson.hibernate.RedissonRegionNativeFactory
hibernate.cache.redisson.entity.Commodity.expiration.max_idle_time=900000

# after
hibernate.cache.region.factory_class=org.redisson.hibernate.RedissonRegionNativeFactory
# (max_idle_time removed; TTL handled natively by Redis)

for (String key : hibernateProps.stringPropertyNames()) {
    if (key.endsWith(".expiration.max_idle_time")
            && Integer.parseInt(hibernateProps.getProperty(key)) > 0) {
        throw new IllegalStateException(key + " must be 0/unset for RedissonRegionNativeFactory");
    }
}

When it happens

Trigger: Starting a SessionFactory with RedissonRegionNativeFactory while any property key ending in .expiration.max_idle_time has a parsed Integer value > 0. The start() property-scan loop throws before the client is created.

Common situations: Copy-pasting cache properties from a RedissonRegionFactory setup (where max_idle_time is valid) into a config now using the native factory; keeping old region tuning when upgrading to the Redis 7 native cache module.

Related errors

• .eviction.max_entries setting can't be non-zero
• .expiration.max_idle_time setting can't be non-zero
• .expiration.max_idle_time setting can't be non-zero
• .eviction.max_entries setting can't be non-zero
• .expiration.max_idle_time setting can't be non-zero

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