hibernate/hibernate-orm · error · IllegalArgumentException

Caching was not configured for entity:

Error message

Caching was not configured for entity: 

What it means

AbstractDomainDataRegion.getEntityDataAccess returns the EntityDataAccess registered for an entity role when the region was built from caching mappings. If the entity has no cache mapping (@org.hibernate.annotations.Cache / <cache usage=.../>), nothing is registered under its NavigableRole and the lookup throws IllegalArgumentException. The request asked a region for entity data caching that was never configured for that entity.

Source

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

	}

	@Nonnull
	public SessionFactoryImplementor getSessionFactory() {
		return sessionFactory;
	}

	@Nonnull
	public CacheKeysFactory getEffectiveKeysFactory() {
		return effectiveKeysFactory;
	}

	@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) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Annotate the entity with @org.hibernate.annotations.Cache(usage = ...) or add <cache usage="..."/> to its mapping
2. Verify persistence.xml shared-cache-mode and hibernate.cache.default_cache_concurrency_strategy actually enable entity caching
3. Check that the NavigableRole string you pass equals the entity name used in mappings
4. Use sessionFactory.getCache() helpers and persister.hasCache() instead of the internal DomainDataRegion API

Example fix

// before
@Entity
public class Country { ... } // no @Cache -> getEntityDataAccess(role) throws

// after
@Entity
@org.hibernate.annotations.Cache(usage = CacheConcurrencyStrategy.READ_ONLY)
public class Country { ... }

EntityPersister persister = sessionFactory.getDomainModel()
        .getEntityDescriptor(Country.class);
if (!persister.hasCache()) {
    // entity caching not configured; skip custom cache handling for this entity
}

When it happens

Trigger: Calling region.getEntityDataAccess(role) or persister cache-access paths for an entity without @Cache; programmatic metadata that skips cache enabling; using a region or role string belonging to a different SessionFactory; enabling only natural-id or collection caching and then requesting entity data access.

Common situations: Assuming shared-cache-mode ENABLE_SELECTIVE or a global default caches every entity; custom cache-management code and tests touching regions while mappings lack @Cache; wrong role strings after entity renames.

Related errors

• Unknown access type [
• Caching was not configured for entity natural id:
• Caching was not configured for collection:
• 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/1da6d576e8edd78b. Report an issue: GitHub.