hibernate/hibernate-orm · error · HibernateException

Cache override referenced an unknown entity : {}

Error message

Cache override referenced an unknown entity : {}

What it means

Error "Cache override referenced an unknown entity : {}" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:1960

		}
	}

	private void processNaturalIdUniqueKeyBinders() {
		if ( naturalIdUniqueKeyBinderMap != null ) {
			for ( var naturalIdUniqueKeyBinder : naturalIdUniqueKeyBinderMap.values() ) {
				naturalIdUniqueKeyBinder.process();
			}
			naturalIdUniqueKeyBinderMap.clear();
		}
	}

	private void processCachingOverrides() {
		if ( bootstrapContext.getCacheRegionDefinitions() != null ) {
			for ( var cacheRegionDefinition : bootstrapContext.getCacheRegionDefinitions() ) {
				if ( cacheRegionDefinition.regionType() == CacheRegionDefinition.CacheRegionType.ENTITY ) {
					final var entityBinding = getEntityBinding( cacheRegionDefinition.role() );
					if ( entityBinding == null ) {
						throw new HibernateException(
								"Cache override referenced an unknown entity : " + cacheRegionDefinition.role()
						);
					}
					if ( !(entityBinding instanceof RootClass rootClass) ) {
						throw new HibernateException(
								"Cache override referenced a non-root entity : " + cacheRegionDefinition.role()
						);
					}
					entityBinding.setCached( true );
					rootClass.setCacheRegionName( cacheRegionDefinition.region() );
					rootClass.setCacheConcurrencyStrategy( cacheRegionDefinition.usage() );
					rootClass.setLazyPropertiesCacheable( cacheRegionDefinition.cacheLazy() );
				}
				else if ( cacheRegionDefinition.regionType() == CacheRegionDefinition.CacheRegionType.COLLECTION ) {
					final var collectionBinding = getCollectionBinding( cacheRegionDefinition.role() );
					if ( collectionBinding == null ) {
						throw new HibernateException(
								"Cache override referenced an unknown collection role : " + cacheRegionDefinition.role()

View on GitHub (pinned to fad1729dce)

Solutions

1. Correct the entity name used in the cache override configuration (e.g. in ehcache/infra config or persistence properties) to a mapped entity.
2. Check for typos and for entities renamed via @Entity(name=...).
3. Remove stale cache configuration entries for entities that no longer exist.

When it happens

Trigger: A mapping references an entity or collection role that is not known at that point.

Common situations: hbm.xml <key> property-refs or jakarta.persistence cache overrides naming entities/roles that are unmapped or not root entities.

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