hibernate/hibernate-orm · error · IllegalArgumentException

Caching was not configured for collection:

Error message

Caching was not configured for collection: 

What it means

getCollectionDataAccess returns the access strategy for a collection role. A CollectionDataAccess is registered only when the collection mapping itself carries cache settings (@Cache on the @OneToMany/@ManyToMany property or <collection-cache/> in hbm.xml). Requesting a collection role without that mapping throws IllegalArgumentException. Caching the owner entity does not cache its collections.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/cache/spi/support/AbstractDomainDataRegion.java:117

	}


	@Override
	@Nonnull
	public NaturalIdDataAccess getNaturalIdDataAccess(@Nonnull NavigableRole rootEntityRole) {
		final var access = naturalIdDataAccessMap.get( rootEntityRole );
		if ( access == null ) {
			throw new IllegalArgumentException( "Caching was not configured for entity natural id: " + rootEntityRole.getFullPath() );
		}
		return access;
	}

	@Override
	@Nonnull
	public CollectionDataAccess getCollectionDataAccess(@Nonnull NavigableRole collectionRole) {
		final var access = collectionDataAccessMap.get( collectionRole );
		if ( access == null ) {
			throw new IllegalArgumentException( "Caching was not configured for collection: " + collectionRole.getFullPath() );
		}
		return access;
	}

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// creation

	@Nonnull
	protected abstract EntityDataAccess generateEntityAccess(@Nonnull EntityDataCachingConfig entityAccessConfig);
	@Nonnull
	protected abstract CollectionDataAccess generateCollectionAccess(@Nonnull CollectionDataCachingConfig cachingConfig);
	@Nonnull
	protected abstract NaturalIdDataAccess generateNaturalIdAccess(@Nonnull NaturalIdDataCachingConfig naturalIdAccessConfig);

	private Map<NavigableRole, EntityDataAccess> generateEntityDataAccessMap(
			@Nonnull DomainDataRegionConfig regionConfig) {
		final var entityCaching = regionConfig.getEntityCaching();
		if ( entityCaching.isEmpty() ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Add @org.hibernate.annotations.Cache(usage = ...) directly on the collection mapping (or <collection-cache collection="..."/> in hbm.xml)
2. Verify the role string equals '<OwnerEntityName>.<propertyName>'
3. Use sessionFactory.getCache() evictCollection* helpers instead of the raw region API
4. Confirm the collection side, not just the entity side, has cache configuration

Example fix

// before
@OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
List<OrderLine> lines; // collection not cached

// after
@OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
List<OrderLine> lines;

CollectionPersister cp = sessionFactory.getDomainModel()
        .findCollectionDescriptor(Order.class.getName() + ".lines");
if (cp == null || !cp.hasCache()) {
    // collection caching not configured; skip cache handling
}

When it happens

Trigger: Calling getCollectionDataAccess for a @OneToMany mapped without @Cache; expecting collection caching because the owner entity is @Cache-annotated; passing a role string like 'Entity.children' that does not exactly match the mapped role.

Common situations: Forgetting the collection-level @Cache annotation; shared-cache-mode setups where collection caching is assumed; typos in role strings inside custom cache tooling.

Related errors

• Unknown access type [
• Caching was not configured for entity:
• Caching was not configured for entity natural id:
• Unknown cache region : {}
• The {storageEngine} storage engine is not supported

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