hibernate/hibernate-orm · error · HibernateException

Cache override referenced a non-root entity : {}

Error message

Cache override referenced a non-root entity : {}

What it means

Error "Cache override referenced a non-root entity : {}" thrown in hibernate/hibernate-orm.

Source

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

			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()
						);
					}
					collectionBinding.setCacheRegionName( cacheRegionDefinition.region() );
					collectionBinding.setCacheConcurrencyStrategy( cacheRegionDefinition.usage() );
				}

View on GitHub (pinned to fad1729dce)

Solutions

1. Point the cache override at the root entity of the inheritance hierarchy instead of a subclass.
2. Move the @Cache annotation / cache configuration to the hierarchy root.
3. Review the inheritance mapping to identify the actual root entity name.

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/a3c60a9349e0e820. Report an issue: GitHub.