hibernate/hibernate-orm · error · AnnotationException

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

Error message

Entity class '${className}' is annotated '@Immutable' but it is a subclass in an entity inheritance hierarchy (only a root class may declare its mutability)

What it means

Error "Entity class '${className}' is annotated '@Immutable' but it is a subclass in an entity inheritance hierarchy (only a root class may declare its mutability)" thrown in hibernate/hibernate-orm.

Source

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

		persistentClass.setProxyInterfaceName( annotatedClass.getName() );

		if ( persistentClass instanceof RootClass ) {
			bindRootEntity();
		}
		else {
			checkSubclassEntity();
		}

		ensureNoMutabilityPlan();

		registerImportName();

		processNamedEntityGraphs();
	}

	private void checkSubclassEntity() {
		if ( !isMutable() ) {
			throw new AnnotationException( "Entity class '" + annotatedClass.getName()
					+ "' is annotated '@Immutable' but it is a subclass in an entity inheritance hierarchy"
					+ " (only a root class may declare its mutability)" );
		}
		if ( isNotBlank( where ) ) {
			throw new AnnotationException( "Entity class '" + annotatedClass.getName()
					+ "' specifies an '@SQLRestriction' but it is a subclass in an entity inheritance hierarchy"
					+ " (only a root class may be specify a restriction)" );
		}
	}

	private void ensureNoMutabilityPlan() {
		if ( annotatedClass.hasAnnotationUsage( Mutability.class, modelsContext() ) ) {
			throw new MappingException( "@Mutability is not allowed on entity" );
		}
	}

	private boolean isMutable() {
		return !annotatedClass.hasAnnotationUsage( Immutable.class, modelsContext() );

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove @Immutable from the subclass; declare mutability only on the hierarchy root.

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/095c662fba898315. Report an issue: GitHub.