hibernate/hibernate-orm · error · AnnotationException

Entity class '${className}' is annotated '@Cache' but it is

Error message

Entity class '${className}' is annotated '@Cache' but it is a subclass in an entity inheritance hierarchy (only root classes may define second-level caching semantics)

What it means

Error "Entity class '${className}' is annotated '@Cache' but it is a subclass in an entity inheritance hierarchy (only root classes may define second-level caching semantics)" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/EntityBinder.java:1914

		isCached = false;
		cacheConcurrentStrategy = null;
		cacheRegion = null;
		cacheLazyProperty = true;
		queryCacheLayout = null;
		if ( isRootEntity() ) {
			bindRootClassCache();
		}
		else {
			bindSubclassCache();
		}
	}

	private void bindSubclassCache() {
		if ( annotatedClass.hasAnnotationUsage( Cache.class, modelsContext() ) ) {
			final String className = persistentClass.getClassName() == null
					? annotatedClass.getName()
					: persistentClass.getClassName();
			throw new AnnotationException("Entity class '" + className
					+  "' is annotated '@Cache' but it is a subclass in an entity inheritance hierarchy"
					+" (only root classes may define second-level caching semantics)");
		}

		final var cacheable = annotatedClass.getAnnotationUsage( Cacheable.class, modelsContext() );
		isCached = cacheable == null && persistentClass.getSuperclass() != null
				// we should inherit the root class caching config
				? persistentClass.getSuperclass().isCached()
				//TODO: is this even correct?
				//      Do we even correctly support selectively enabling caching on subclasses like this?
				: isCacheable( cacheable );
	}

	private void bindRootClassCache() {
		final var sourceModelContext = modelsContext();

		final var cache = annotatedClass.getAnnotationUsage( Cache.class, sourceModelContext );
		final var cacheable = annotatedClass.getAnnotationUsage( Cacheable.class, sourceModelContext );

View on GitHub (pinned to fad1729dce)

Solutions

1. Move @Cache to the root class of the entity inheritance hierarchy.

When it happens

Trigger: An annotation restricted to the root of an inheritance hierarchy is placed on a subclass (or the hierarchy rules are otherwise violated).

Common situations: SINGLE_TABLE/JOINED hierarchies where @Table, @DiscriminatorColumn, @DiscriminatorFormula, @Cache, @Immutable, @Id or @Version are declared on the wrong class of the hierarchy.

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