{"record":{"id":"a000619e4c4e5d0a","repo":"hibernate/hibernate-orm","slug":"cache-override-referenced-an-unknown-entity","errorCode":null,"errorMessage":"Cache override referenced an unknown entity : {}","messagePattern":"Cache override referenced an unknown entity : (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":1960,"sourceCode":"\t\t}\n\t}\n\n\tprivate void processNaturalIdUniqueKeyBinders() {\n\t\tif ( naturalIdUniqueKeyBinderMap != null ) {\n\t\t\tfor ( var naturalIdUniqueKeyBinder : naturalIdUniqueKeyBinderMap.values() ) {\n\t\t\t\tnaturalIdUniqueKeyBinder.process();\n\t\t\t}\n\t\t\tnaturalIdUniqueKeyBinderMap.clear();\n\t\t}\n\t}\n\n\tprivate void processCachingOverrides() {\n\t\tif ( bootstrapContext.getCacheRegionDefinitions() != null ) {\n\t\t\tfor ( var cacheRegionDefinition : bootstrapContext.getCacheRegionDefinitions() ) {\n\t\t\t\tif ( cacheRegionDefinition.regionType() == CacheRegionDefinition.CacheRegionType.ENTITY ) {\n\t\t\t\t\tfinal var entityBinding = getEntityBinding( cacheRegionDefinition.role() );\n\t\t\t\t\tif ( entityBinding == null ) {\n\t\t\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\t\t\"Cache override referenced an unknown entity : \" + cacheRegionDefinition.role()\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tif ( !(entityBinding instanceof RootClass rootClass) ) {\n\t\t\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\t\t\"Cache override referenced a non-root entity : \" + cacheRegionDefinition.role()\n\t\t\t\t\t\t);\n\t\t\t\t\t}\n\t\t\t\t\tentityBinding.setCached( true );\n\t\t\t\t\trootClass.setCacheRegionName( cacheRegionDefinition.region() );\n\t\t\t\t\trootClass.setCacheConcurrencyStrategy( cacheRegionDefinition.usage() );\n\t\t\t\t\trootClass.setLazyPropertiesCacheable( cacheRegionDefinition.cacheLazy() );\n\t\t\t\t}\n\t\t\t\telse if ( cacheRegionDefinition.regionType() == CacheRegionDefinition.CacheRegionType.COLLECTION ) {\n\t\t\t\t\tfinal var collectionBinding = getCollectionBinding( cacheRegionDefinition.role() );\n\t\t\t\t\tif ( collectionBinding == null ) {\n\t\t\t\t\t\tthrow new HibernateException(\n\t\t\t\t\t\t\t\t\"Cache override referenced an unknown collection role : \" + cacheRegionDefinition.role()","sourceCodeStart":1942,"sourceCodeEnd":1978,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L1942-L1978","documentation":"Error \"Cache override referenced an unknown entity : {}\" thrown in hibernate/hibernate-orm.","triggerScenarios":"A mapping references an entity or collection role that is not known at that point.","commonSituations":"hbm.xml <key> property-refs or jakarta.persistence cache overrides naming entities/roles that are unmapped or not root entities.","solutions":["Correct the entity name used in the cache override configuration (e.g. in ehcache/infra config or persistence properties) to a mapped entity.","Check for typos and for entities renamed via @Entity(name=...).","Remove stale cache configuration entries for entities that no longer exist."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}