{"record":{"id":"c63542e9e392e16c","repo":"hibernate/hibernate-orm","slug":"unknown-cache-region","errorCode":null,"errorMessage":"Unknown cache region : {}","messagePattern":"Unknown cache region : (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsImpl.java","lineNumber":1015,"sourceCode":"\t\treturn new EntityStatisticsImpl( metamodel.getEntityDescriptor( entityName ) );\n\t}\n\n\tprivate CollectionStatisticsImpl instantiateCollectionStatistics(final String role) {\n\t\treturn new CollectionStatisticsImpl( metamodel.getCollectionDescriptor( role ) );\n\t}\n\n\tprivate NaturalIdStatisticsImpl instantiateNaturalStatistics(final String entityName) {\n\t\tfinal EntityPersister entityDescriptor = metamodel.getEntityDescriptor( entityName );\n\t\tif ( !entityDescriptor.hasNaturalIdentifier() ) {\n\t\t\tthrow new IllegalArgumentException( \"Given entity [\" + entityName + \"] does not define natural-id\" );\n\t\t}\n\t\treturn new NaturalIdStatisticsImpl( entityDescriptor );\n\t}\n\n\tprivate CacheRegionStatisticsImpl instantiateCacheRegionStatistics(final String regionName) {\n\t\tfinal Region region = cache.getRegion( regionName );\n\t\tif ( region == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Unknown cache region : \" + regionName );\n\t\t}\n\t\tif ( region instanceof QueryResultsRegion ) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Region name [\" + regionName + \"] referred to a query result region, not a domain data region\"\n\t\t\t);\n\t\t}\n\t\treturn new CacheRegionStatisticsImpl( region );\n\t}\n\n\tprivate CacheRegionStatisticsImpl instantiateCacheRegionStatsForQueryResults(final String regionName) {\n\t\treturn new CacheRegionStatisticsImpl( cache.getQueryResultsCache( regionName ).getRegion() );\n\t}\n\n\tprivate @Nullable CacheRegionStatisticsImpl createCacheRegionStatistics(final String regionName) {\n\t\tRegion region = cache.getRegion( regionName );\n\t\tif ( region == null ) {\n\t\t\tif ( !queryCacheEnabled ) {\n\t\t\t\treturn null;","sourceCodeStart":997,"sourceCodeEnd":1033,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/stat/internal/StatisticsImpl.java#L997-L1033","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Enumerate the real names first via Statistics#getSecondLevelCacheRegionNames() and drive your dashboard from that list."],"exampleFix":"// before\nCacheRegionStatistics s = statistics.getDomainDataRegionStatistics(\"users\");\n// IllegalArgumentException: region never created\n\n// after\nboolean known = Arrays.asList(statistics.getSecondLevelCacheRegionNames()).contains(\"users\");\nCacheRegionStatistics s = known ? statistics.getDomainDataRegionStatistics(\"users\") : null;","handlingStrategy":"validation","validationCode":"String[] known = statistics.getSecondLevelCacheRegionNames();\nif (Arrays.asList(known).contains(regionName)) {\n    CacheRegionStatistics s = statistics.getDomainDataRegionStatistics(regionName);\n}","typeGuard":null,"tryCatchPattern":"try {\n    CacheRegionStatistics s = statistics.getDomainDataRegionStatistics(regionName);\n} catch (IllegalArgumentException e) {\n    // region not created — verify 2LC config and region name/prefix\n    log.warn(\"Unknown cache region {}\", regionName);\n}","preventionTips":["Drive dashboards from Statistics#getSecondLevelCacheRegionNames() instead of hard-coded names.","Enable the second-level cache (RegionFactory + @Cache) before collecting region statistics.","Account for hibernate.cache.region_prefix when composing region names."],"tags":["hibernate","second-level-cache","statistics","cache-region","configuration"],"backgroundTag":"unknown-cache-region","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}