hibernate/hibernate-orm · error · MappingException

Interface '<clazz.getName()>' may not be annotated '@Entity'

Error message

Interface '<clazz.getName()>' may not be annotated '@Entity'

What it means

Error "Interface '<clazz.getName()>' may not be annotated '@Entity'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/annotations/AnnotationMetadataSourceProcessorImpl.java:241

	}

	private List<ClassDetails> orderAndFillHierarchy(LinkedHashSet<ClassDetails> original) {
		final LinkedHashSet<ClassDetails> copy = new LinkedHashSet<>( original.size() );
		insertMappedSuperclasses( original, copy );
		// order the hierarchy
		final List<ClassDetails> workingCopy = new ArrayList<>( copy );
		final List<ClassDetails> newList = new ArrayList<>( copy.size() );
		while ( !workingCopy.isEmpty() ) {
			final var clazz = workingCopy.get( 0 );
			orderHierarchy( workingCopy, newList, copy, clazz );
		}
		return newList;
	}

	private void insertMappedSuperclasses(LinkedHashSet<ClassDetails> original, LinkedHashSet<ClassDetails> copy) {
		for ( var clazz : original ) {
			if ( clazz.isInterface() && isEntity( clazz ) ) {
				throw new MappingException( "Interface '" + clazz.getName() + "' may not be annotated '@Entity'" );
			}
			else if ( isMappedSuperclass( clazz ) ) {
				// Skip class with explicit @MappedSuperclass annotation
				// the class will be discovered analyzing the implementing class
			}
			else {
				copy.add( clazz );
				var superClass = clazz.getSuperClass();
				while ( superClass != null
						&& !isObjectClass( superClass )
						&& !copy.contains( superClass ) ) {
					if ( isEntity( superClass ) || isMappedSuperclass( superClass ) ) {
						copy.add( superClass );
					}
					superClass = superClass.getSuperClass();
				}
			}
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove @Entity from the interface; map a concrete class instead, or use the interface only as a target of associations via targetEntity.

Example fix

Remove @Entity from the interface; map a concrete class instead, or use the interface only as a target of associations via targetEntity.

When it happens

Trigger: An entity mapping annotation or bootstrap configuration violates a Hibernate mapping rule.

Common situations: Annotation mapping mistakes: inverse-side @Id associations, @Column on @OneToOne, unmapped association targets, mismatched @EnumeratedValue/@Temporal usage, duplicate sequence generators.

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