quarkusio/quarkus · error · IllegalStateException

The maximum size can only be changed if the cache was constr

Error message

The maximum size can only be changed if the cache was constructed with a maximum-size configuration value

What it means

CaffeineCacheImpl.setMaximumSize can only change the bound if the cache was built with a maximum-size configuration value, because Caffeine's Policy.Eviction is only available for size-bounded caches. Without it, an IllegalStateException is thrown.

Source

Thrown at extensions/cache/runtime/src/main/java/io/quarkus/cache/runtime/caffeine/CaffeineCacheImpl.java:325

    public void setExpireAfterAccess(Duration duration) {
        Optional<FixedExpiration<Object, Object>> fixedExpiration = cache.synchronous().policy().expireAfterAccess();
        if (fixedExpiration.isPresent()) {
            fixedExpiration.get().setExpiresAfter(duration);
            cacheInfo.expireAfterAccess = duration;
        } else {
            throw new IllegalStateException("The access-based expiration policy can only be changed if the cache was " +
                    "constructed with an expire-after-access configuration value");
        }
    }

    @Override
    public void setMaximumSize(long maximumSize) {
        Optional<Policy.Eviction<Object, Object>> eviction = cache.synchronous().policy().eviction();
        if (eviction.isPresent()) {
            eviction.get().setMaximum(maximumSize);
            cacheInfo.maximumSize = maximumSize;
        } else {
            throw new IllegalStateException("The maximum size can only be changed if the cache was constructed with a " +
                    "maximum-size configuration value");
        }
    }

    // For testing purposes only.
    public CaffeineCacheInfo getCacheInfo() {
        return cacheInfo;
    }

    public long getSize() {
        return cache.synchronous().estimatedSize();
    }

    @SuppressWarnings("unchecked")
    private <T> T cast(Object value) {
        try {
            return (T) value;
        } catch (ClassCastException e) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Add quarkus.cache.caffeine.<name>.maximum-size to configuration so the cache is size-bounded at build time
2. Only call setMaximumSize on caches known to be size-bounded
3. Recreate the cache with a maximum-size value

Example fix

// before
# cache without maximum-size
cache.setMaximumSize(1000);
// after
# application.properties
quarkus.cache.caffeine.myCache.maximum-size=1000

if (cache.getCacheInfo().maximumSize == null) {
    throw new IllegalStateException("configure maximum-size before calling setMaximumSize");
}

try {
    cache.setMaximumSize(1000);
} catch (IllegalStateException e) {
    log.warn("cache is not size-bounded; set maximum-size in config", e);
}

When it happens

Trigger: Calling setMaximumSize (e.g. from testConfig) on a cache created without quarkus.cache.caffeine.<name>.maximum-size.

Common situations: Trying to add a size cap at runtime to an unbounded cache (e.g. configured only with expiration settings).

Related errors

• The write-based expiration policy can only be changed if the
• The access-based expiration policy can only be changed if th
• Unknown cache type:
• An existing cached value type does not match the requested t
• An existing cached value type does not match the type return

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b4f2f44194c6f070. Report an issue: GitHub.