hibernate/hibernate-orm · error · AnnotationException

Mapped superclass '{}' may not specify an '@Inheritance' map

Error message

Mapped superclass '{}' may not specify an '@Inheritance' mapping strategy

What it means

A '@MappedSuperclass' declares a direct '@Inheritance' annotation. Inheritance strategies (SINGLE_TABLE, JOINED, TABLE_PER_CLASS) are per-hierarchy and belong on the root '@Entity' of the hierarchy; a mapped superclass is not part of that decision, so Hibernate rejects the annotation.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/AnnotationBinder.java:295

			final String name = unqualify( qualifiedName );
			final String rename = annotatedClass.getDirectAnnotationUsage( Imported.class ).rename();
			context.getMetadataCollector().addImport( rename.isBlank() ? name : rename, qualifiedName );
		}
	}

	private static void detectMappedSuperclassProblems(ClassDetails annotatedClass) {
		if ( isMappedSuperclass( annotatedClass ) ) {
			// @Entity and @MappedSuperclass on the same class leads to NPE down the road
			if ( isEntity( annotatedClass ) ) {
				throw new AnnotationException( "Type '" + annotatedClass.getName()
						+ "' is annotated both '@Entity' and '@MappedSuperclass'" );
			}
			if ( annotatedClass.hasDirectAnnotationUsage( Table.class ) ) {
				throw new AnnotationException( "Mapped superclass '" + annotatedClass.getName()
						+ "' may not specify a '@Table'" );
			}
			if ( annotatedClass.hasDirectAnnotationUsage( Inheritance.class ) ) {
				throw new AnnotationException( "Mapped superclass '" + annotatedClass.getName()
						+ "' may not specify an '@Inheritance' mapping strategy" );
			}
		}
	}

	private static void bindTypeDescriptorRegistrations(
			AnnotationTarget annotatedElement,
			MetadataBuildingContext context) {
		final var managedBeanRegistry = context.getBootstrapContext().getManagedBeanRegistry();
		final var sourceModelContext = modelsContext( context );

		annotatedElement.forEachAnnotationUsage(
				JavaTypeRegistration.class,
				sourceModelContext,
				usage -> handleJavaTypeRegistration( context, managedBeanRegistry, usage )
		);

		annotatedElement.forEachAnnotationUsage(

View on GitHub (pinned to fad1729dce)

Solutions

Remove '@Inheritance' from the mapped superclass.
Put '@Inheritance(strategy = ...)' on the ROOT @Entity of the hierarchy that each concrete subclass extends.
If the base class must carry the strategy, make it an '@Entity' root instead of a '@MappedSuperclass'.

Example fix

// before
@MappedSuperclass
@Inheritance(strategy = InheritanceType.JOINED) // -> error
public abstract class BaseThing { @Id Long id; }

// after
@MappedSuperclass
public abstract class BaseThing { @Id Long id; }

@Entity
@Inheritance(strategy = InheritanceType.JOINED)
public abstract class Thing extends BaseThing { ... }

Defensive patterns

Strategy: validation

Validate before calling

// Guard: mapped superclasses must not declare @Inheritance
if (cls.isAnnotationPresent(MappedSuperclass.class)
        && cls.isAnnotationPresent(Inheritance.class)) {
    throw new IllegalStateException(
        cls.getName() + ": @MappedSuperclass may not declare @Inheritance");
}

Try / catch

try {
    Metadata md = sources.buildMetadata();
} catch (AnnotationException e) {
    // 'may not specify an @Inheritance mapping strategy' -> move @Inheritance
    // to the root @Entity of the hierarchy
    throw newConfigurationException("Illegal @Inheritance on superclass", e);
}

Prevention

Declare @Inheritance exactly once, on the root @Entity of each hierarchy.
Do not copy full root-entity annotation sets onto new superclasses.

When it happens

Trigger: '@MappedSuperclass @Inheritance(strategy = InheritanceType.JOINED)' on an abstract base; pulling a root entity's annotations up while converting it to a superclass; copy-pasting a full annotation set onto a new base class.

Common situations: Reorganizing class hierarchies and moving @Inheritance 'for reuse'; mixing @MappedSuperclass chains with @Entity inheritance chains in the same codebase.

Related errors

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