hibernate/hibernate-orm · error · AnnotationException

Entity '{}' may not override the inheritance mapping strateg

Error message

Entity '{}' may not override the inheritance mapping strategy '{}' of its hierarchy' (each entity hierarchy has a single inheritance mapping strategy)

What it means

An entity declares an '@Inheritance' strategy that differs from the strategy already established by its mapped superclass/ancestor in the same hierarchy. JPA allows exactly ONE inheritance strategy per entity hierarchy, declared on the root; Hibernate enforces this whenever the subclass picks a non-default strategy that conflicts with the hierarchy's (non-default = anything other than the SINGLE_TABLE default).

Source

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

					state.setType( inheritanceType );
				}
			}
			switch ( classType ) {
				case ENTITY, MAPPED_SUPERCLASS, EMBEDDABLE:
					inheritanceStatePerClass.put( classDetails, state );
			}
		}
		return inheritanceStatePerClass;
	}

	private static void checkMixedInheritance(ClassDetails classDetails, InheritanceState superclassState, InheritanceState state) {
		final var inheritanceType = state.getType();
		final var superclassInheritanceType = superclassState.getType();
		if ( inheritanceType != null && superclassInheritanceType != null ) {
			final boolean nonDefault = SINGLE_TABLE != inheritanceType;
			final boolean mixingStrategy = inheritanceType != superclassInheritanceType;
			if ( nonDefault && mixingStrategy ) {
				throw new AnnotationException( "Entity '" + classDetails.getName()
						+ "' may not override the inheritance mapping strategy '" + superclassInheritanceType
						+ "' of its hierarchy"
						+ "' (each entity hierarchy has a single inheritance mapping strategy)" );
			}
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Remove '@Inheritance' from the subclass named in the message — only the hierarchy root defines the strategy.
Choose ONE strategy for the whole hierarchy and declare it once on the root @Entity.
If different branches truly need different strategies, split them into separate, independent hierarchies (separate roots).

Example fix

// before
@Entity
@Inheritance(strategy = InheritanceType.JOINED)
abstract class BillingDocument { @Id Long id; }

@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE) // -> error: override
class Invoice extends BillingDocument { ... }

// after
@Entity
class Invoice extends BillingDocument { ... } // strategy only on the root

Defensive patterns

Strategy: validation

Validate before calling

// Guard: @Inheritance only on hierarchy roots, one strategy per hierarchy
Class<?> c = cls;
while (c.getSuperclass() != null) {
    c = c.getSuperclass();
    Inheritance parent = c.getAnnotation(Inheritance.class);
    Inheritance mine = cls.getAnnotation(Inheritance.class);
    if (parent != null && mine != null
            && mine.strategy() != parent.strategy()) {
        throw new IllegalStateException(cls.getName()
            + " overrides hierarchy inheritance strategy");
    }
}

Try / catch

try {
    Metadata md = sources.buildMetadata();
} catch (AnnotationException e) {
    // 'may not override the inheritance mapping strategy' -> delete @Inheritance
    // from the subclass; keep one strategy on the root
    throw newConfigurationException("Inheritance strategy conflict", e);
}

Prevention

Declare @Inheritance once, on the root entity; subclasses inherit the strategy implicitly.
If branches need different strategies, split into independent hierarchies with separate roots.

When it happens

Trigger: Root entity '@Inheritance(JOINED)' and a subclass declaring '@Inheritance(SINGLE_TABLE)' (or TABLE_PER_CLASS); ancestors chain where an intermediate class redeclares @Inheritance with a different type; checkMixedInheritance fires when both this state's type and the superclass state's type are non-null, differ, and the subclass type is not the SINGLE_TABLE default.

Common situations: Copy-pasting the root's @Inheritance line onto subclasses and editing the strategy per class; merging two hierarchies that used different strategies; believing each level can pick its own mapping strategy.

Related errors

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