hibernate/hibernate-orm · error · IllegalArgumentException

Caching was not configured for entity natural id:

Error message

Caching was not configured for entity natural id: 

What it means

getNaturalIdDataAccess returns the access object for an entity's natural-id cache. It is registered only when the mapping enables natural-id caching: the entity is @Cache-annotated, carries @NaturalId fields, and natural-id caching is requested via @NaturalIdCache (or the hbm.xml natural-id cache setting). Otherwise no NaturalIdDataAccess exists for the role and the lookup throws IllegalArgumentException.

Source

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

	}

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


	@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

View on GitHub (pinned to fad1729dce)

Solutions

1. Add @org.hibernate.annotations.NaturalIdCache to the entity (and keep @Cache on it plus @NaturalId on the fields)
2. Confirm entity-level caching is enabled - natural-id caching only works on top of entity caching
3. Check the role string matches the entity name used in mappings
4. Use sessionFactory.getCache().evictNaturalId* helpers rather than the raw region API

Example fix

// before
@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class User { @NaturalId String ssn; } // no natural-id cache registered

// after
@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@NaturalIdCache
public class User { @NaturalId String ssn; }

if (sessionFactory.getDomainModel().getEntityDescriptor(User.class)
        .getNaturalIdCacheAccessStrategy() == null) {
    // natural-id caching not enabled; avoid getNaturalIdDataAccess for this entity
}

When it happens

Trigger: Calling getNaturalIdDataAccess for an entity lacking @NaturalIdCache; session.bySimpleNaturalId().load() flows assuming natural-id caching defaults to on; programmatic cache eviction/management touching natural-id regions that were never built.

Common situations: Adding @NaturalId without @NaturalIdCache and expecting L2 hits on natural-id lookups; refactors that drop the annotation; test SessionFactories built with minimal mappings.

Related errors

• Unknown access type [
• Caching was not configured for entity:
• Caching was not configured for collection:
• Unknown cache region : {}
• AnyType not supported as part of cache key!

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