hibernate/hibernate-orm · error · MappingException

@Mutability is not allowed on entity

Error message

@Mutability is not allowed on entity

What it means

Error "@Mutability is not allowed on entity" thrown in hibernate/hibernate-orm.

Source

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

		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() );
	}

	private void registerImportName() {
		try {
			final var metadataCollector = getMetadataCollector();
			metadataCollector.addImport( name, persistentClass.getEntityName() );
			final String entityName = persistentClass.getEntityName();
			if ( !entityName.equals( name ) ) {
				metadataCollector.addImport( entityName, entityName );
			}
		}
		catch (MappingException me) {
			throw new AnnotationException( "Use of the same entity name twice: " + name, me );

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove @Mutability from the entity; it is not allowed on entity types.

When it happens

Trigger: @Mutability is placed on an entity, where mutability customizations are not supported.

Common situations: @Mutability applied to an @Entity; it is only meaningful for basic-typed attributes and embeddables.

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