hibernate/hibernate-orm · error · IllegalArgumentException

Unknown cache region : {}

Error message

Unknown cache region : {}

What it means

StatisticsImpl#instantiateCacheRegionStatistics resolves the requested name through the CacheImplementor; a null Region means no second-level-cache region with that name was ever created, so getDomainDataRegionStatistics (and the generic cache-region statistics accessor) rejects the name with an IllegalArgumentException.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsImpl.java:1015

		return new EntityStatisticsImpl( metamodel.getEntityDescriptor( entityName ) );
	}

	private CollectionStatisticsImpl instantiateCollectionStatistics(final String role) {
		return new CollectionStatisticsImpl( metamodel.getCollectionDescriptor( role ) );
	}

	private NaturalIdStatisticsImpl instantiateNaturalStatistics(final String entityName) {
		final EntityPersister entityDescriptor = metamodel.getEntityDescriptor( entityName );
		if ( !entityDescriptor.hasNaturalIdentifier() ) {
			throw new IllegalArgumentException( "Given entity [" + entityName + "] does not define natural-id" );
		}
		return new NaturalIdStatisticsImpl( entityDescriptor );
	}

	private CacheRegionStatisticsImpl instantiateCacheRegionStatistics(final String regionName) {
		final Region region = cache.getRegion( regionName );
		if ( region == null ) {
			throw new IllegalArgumentException( "Unknown cache region : " + regionName );
		}
		if ( region instanceof QueryResultsRegion ) {
			throw new IllegalArgumentException(
					"Region name [" + regionName + "] referred to a query result region, not a domain data region"
			);
		}
		return new CacheRegionStatisticsImpl( region );
	}

	private CacheRegionStatisticsImpl instantiateCacheRegionStatsForQueryResults(final String regionName) {
		return new CacheRegionStatisticsImpl( cache.getQueryResultsCache( regionName ).getRegion() );
	}

	private @Nullable CacheRegionStatisticsImpl createCacheRegionStatistics(final String regionName) {
		Region region = cache.getRegion( regionName );
		if ( region == null ) {
			if ( !queryCacheEnabled ) {
				return null;

View on GitHub (pinned to fad1729dce)

Solutions

1. Enable the second-level cache with a RegionFactory (Ehcache, Caffeine, Infinispan) and map the entity/collection with @Cache(usage=..., region="...") so the region is actually created.
2. Pass the exact runtime region name: the @Cache region attribute or the entity/collection role, including the hibernate.cache.region_prefix if one is set.
3. Enumerate the real names first via Statistics#getSecondLevelCacheRegionNames() and drive your dashboard from that list.

Example fix

// before
CacheRegionStatistics s = statistics.getDomainDataRegionStatistics("users");
// IllegalArgumentException: region never created

// after
boolean known = Arrays.asList(statistics.getSecondLevelCacheRegionNames()).contains("users");
CacheRegionStatistics s = known ? statistics.getDomainDataRegionStatistics("users") : null;

String[] known = statistics.getSecondLevelCacheRegionNames();
if (Arrays.asList(known).contains(regionName)) {
    CacheRegionStatistics s = statistics.getDomainDataRegionStatistics(regionName);
}

try {
    CacheRegionStatistics s = statistics.getDomainDataRegionStatistics(regionName);
} catch (IllegalArgumentException e) {
    // region not created — verify 2LC config and region name/prefix
    log.warn("Unknown cache region {}", regionName);
}

When it happens

Trigger: Calling statistics.getDomainDataRegionStatistics("myRegion") when no @Cache(region="myRegion") entity/collection mapping and no explicit region configuration ever created that region; also asking for region statistics when second-level caching is not enabled (no RegionFactory), or ignoring that hibernate.cache.region_prefix is prepended to region names.

Common situations: Hard-coded region names in dashboards after entity renames; collecting statistics on environments where hibernate.cache.use_second_level_cache=false; a region prefix set on one node but not another; using the entity class name instead of the configured region name.

Related errors

• Unknown access type [
• Caching was not configured for entity:
• Caching was not configured for entity natural id:
• Caching was not configured for collection:
• Region name [{}] referred to a query result region, not a do

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/c63542e9e392e16c. Report an issue: GitHub.