hibernate/hibernate-orm · error · HibernateException

Cache override referenced an unknown collection role : {}

Error message

Cache override referenced an unknown collection role : {}

What it means

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

Source

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

					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() );
				}
			}
		}
	}

	@Override
	public boolean isInSecondPass() {
		return inSecondPass;
	}

	/**
	 * Builds the complete and immutable Metadata instance from the collected info.
	 *

View on GitHub (pinned to fad1729dce)

Solutions

1. Use the exact collection role (entityName.propertyName) in the cache configuration; check spelling of both parts.
2. Confirm the collection is actually mapped with the given property name on the stated entity.
3. Remove cache settings for collections that were renamed or deleted.

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