quarkusio/quarkus · error · IllegalStateException

Cache for region %s not found

Error message

Cache for region %s not found

What it means

This endpoint method unwraps the Hibernate SessionFactory cache, obtains the JCacheRegionFactory's CacheManager, and looks up the JCache for a given second-level-cache region name. If the CacheManager has no cache registered under that region name, it throws this IllegalStateException. It signals that the requested Hibernate cache region was never created — typically because no entity/collection/query is configured to use that region.

Source

Thrown at integration-tests/hibernate-orm-cache/src/main/java/io/quarkus/it/hibernate/orm/cache/HibernateOrmCacheTestEndpoint.java:100

                .orElse("not-set");
    }

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    @Path("/has-weigher/{region}")
    public String hasWeigher(@PathParam("region") String region) {
        CaffeineConfiguration<?, ?> config = getCacheConfig(region);
        return String.valueOf(config.getWeigherFactory().isPresent());
    }

    private Cache<?, ?> getRegionCache(String region) {
        var sessionFactory = emf.unwrap(SessionFactory.class);
        var cache = (CacheImplementor) sessionFactory.getCache();
        var regionFactory = (JCacheRegionFactory) cache.getRegionFactory();
        var cacheManager = regionFactory.getCacheManager();
        Cache<?, ?> regionCache = cacheManager.getCache(region);
        if (regionCache == null) {
            throw new IllegalStateException(String.format("Cache for region %s not found", region));
        }
        return regionCache;
    }

    private CaffeineConfiguration<?, ?> getCacheConfig(String region) {
        return getRegionCache(region).getConfiguration(CaffeineConfiguration.class);
    }

    /**
     * Lists the various operations we want to test for:
     */
    private void doStuffWithHibernate() {
        //Cleanup any existing data:
        deleteAll();

        testReadOnly();
        testReadWrite();
        testNonStrictReadWrite();

View on GitHub (pinned to e1c734241f)

Solutions

  1. Verify the region name matches the entity FQCN or collection role exactly (case-sensitive)
  2. Ensure the entity/collection is annotated with @Cache or configured via quarkus.hibernate-orm cache properties so the region is created
  3. Access the cached entity/collection once before querying statistics so the region is initialized
  4. Check the configured cache backend supports/creates the expected regions

Example fix

// before
cacheManager.getCache(region); // null for 'com.example.Item' if Item has no @Cache
// after
@Entity
@Cacheable
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_ONLY, region = "com.example.Item")
public class Item { ... }
Defensive patterns

Strategy: validation

Validate before calling

Cache<?, ?> regionCache = regionFactory.getCacheManager().getCache(region);
if (regionCache == null) {
    throw new ResponseStatusException(404, "Unknown cache region: " + region + "; check @Cache mappings and quarkus.hibernate-orm cache config");
}

Try / catch

try {
    Cache<?, ?> c = getRegionCache(region);
} catch (IllegalStateException e) {
    // fall back: list available regions
    Set<String> known = cache.getCacheNames();
    throw new IllegalArgumentException("Region '" + region + "' not found; known: " + known);
}

Prevention

When it happens

Trigger: GET to the test endpoint with a region name (entity or collection region, e.g. an entity class FQCN or collection role) that has no corresponding @Cacheable/@Cache mapping or is not present in quarkus.hibernate-orm.cache.* configuration, so JCacheRegionFactory never created that cache.

Common situations: Typo in region name passed as query param; entity missing @Cache annotation or quarkus.hibernate-orm second-level cache config removed; cache region not yet initialized because no access touched it; switching cache backends (e.g. from Caffeine to Infinispan) where region naming differs.

Related errors

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