hibernate/hibernate-orm · error · AnnotationException

Embeddable class '%s' defines an inheritance hierarchy and c

Error message

Embeddable class '%s' defines an inheritance hierarchy and cannot be used with a custom '@CompositeType'

What it means

Error "Embeddable class '%s' defines an inheritance hierarchy and cannot be used with a custom '@CompositeType'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/EmbeddableBinder.java:733

	}

	private static void validateInheritanceIsSupported(
			PropertyHolder holder,
			CompositeUserType<?> compositeUserType) {
		if ( holder.isOrWithinEmbeddedId() ) {
			throw new AnnotationException( String.format(
					"Embeddable class '%s' defines an inheritance hierarchy and cannot be used in an '@EmbeddedId'",
					holder.getClassName()
			) );
		}
		else if ( holder.isInIdClass() ) {
			throw new AnnotationException( String.format(
					"Embeddable class '%s' defines an inheritance hierarchy and cannot be used in an '@IdClass'",
					holder.getClassName()
			) );
		}
		else if ( compositeUserType != null ) {
			throw new AnnotationException( String.format(
					"Embeddable class '%s' defines an inheritance hierarchy and cannot be used with a custom '@CompositeType'",
					holder.getClassName()
			) );
		}
	}

	private static List<PropertyData> collectClassElements(
			AccessType propertyAccessor,
			MetadataBuildingContext context,
			ClassDetails returnedClassOrElement,
			TypeDetails annotatedClass,
			boolean isIdClass,
			Map<String, String> subclassToSuperclass) {
		final List<PropertyData> classElements = new ArrayList<>();
		//embeddable elements can have type defs
		final var container = new PropertyContainer( returnedClassOrElement, annotatedClass, propertyAccessor );
		addElementsOfClass( classElements, container, context, 0 );
		//add elements of the embeddable's mapped superclasses

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the custom @CompositeType or use an embeddable without inheritance for the composite type.

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/5ac34b83831b9fa3. Report an issue: GitHub.