hibernate/hibernate-orm · error · AnnotationException

Class '<componentClassName>' is an '@Embeddable' type and ma

Error message

Class '<componentClassName>' is an '@Embeddable' type and may not be annotated '@DiscriminatorOptions'

What it means

The Component overload of DiscriminatorOptionsBinder.bind always throws: @DiscriminatorOptions on an @Embeddable class is rejected because embeddables take no part in entity inheritance hierarchies and have no discriminator column to configure.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/binder/internal/DiscriminatorOptionsBinder.java:41

	@Override
	public void bind(DiscriminatorOptions options, MetadataBuildingContext context, PersistentClass persistentClass) {
		if ( persistentClass instanceof RootClass rootClass ) {
			if ( !rootClass.hasDiscriminator() ) {
				throw new AnnotationException( "Root entity '" + rootClass.getEntityName()
						+ "' is annotated '@DiscriminatorOptions' but has no discriminator column" );
			}
			rootClass.setForceDiscriminator( options.force() );
			rootClass.setDiscriminatorInsertable( options.insert() );
		}
		else {
			throw new AnnotationException("Class '" + persistentClass.getClassName()
					+ "' is not the root class of an entity inheritance hierarchy and may not be annotated '@DiscriminatorOptions'");
		}
	}

	@Override
	public void bind(DiscriminatorOptions options, MetadataBuildingContext context, Component embeddableClass) {
		throw new AnnotationException("Class '" + embeddableClass.getComponentClassName()
				+ "' is an '@Embeddable' type and may not be annotated '@DiscriminatorOptions'");
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove @DiscriminatorOptions from the @Embeddable class.
2. If the class needs inheritance with a discriminator, map it as an entity hierarchy — @DiscriminatorOptions never applies to embeddables.

Example fix

// before
@Embeddable
@DiscriminatorOptions(force = true)
public class Address { ... }

// after
@Embeddable
public class Address { ... }

for (Class<?> cls : persistentClasses) {
    if (cls.isAnnotationPresent(jakarta.persistence.Embeddable.class)
            && cls.isAnnotationPresent(org.hibernate.annotations.DiscriminatorOptions.class)) {
        throw new IllegalStateException("@DiscriminatorOptions not allowed on @Embeddable " + cls.getName());
    }
}

Catch org.hibernate.AnnotationException during SessionFactory build; abort with the class name from the message.

When it happens

Trigger: An @Embeddable class annotated @DiscriminatorOptions is registered in the metadata; SessionFactory bootstrap binds the Component mapping and throws unconditionally.

Common situations: Annotation sweeps or IDE templates applying inheritance options to all classes; embeddables that used to be entities; misunderstanding @DiscriminatorOptions as related to embeddable polymorphism.

Related errors

• Class '<componentClassName>' is an '@Embeddable' type and ma
• Root entity '<entityName>' is annotated '@DiscriminatorOptio
• Class '<className>' is not the root class of an entity inher
• Property '<propertyName>' may not be annotated '@BatchSize'
• One to many association '<propertyName>' was annotated '@Col

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