hibernate/hibernate-orm · error · AnnotationException

Error processing @TypeBinderType annotation '%s' for embedda

Error message

Error processing @TypeBinderType annotation '%s' for embeddable type '%s'

What it means

Hibernate throws this AnnotationException while binding an @Embeddable class when a custom binder registered through @TypeBinderType fails. The exception only wraps the real failure: the original exception thrown inside your TypeBinder.bind() implementation (or while instantiating the binder) is attached as the cause. Fix the cause, not this message.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/Binders.java:36

import static org.hibernate.internal.util.GenericsHelper.typeArguments;

/**
 * @author Gavin King
 * @since 7.3
 */
public class Binders {
	static <A extends Annotation> void callTypeBinder(
			Annotation annotation, Class<A> annotationType,
			Component embeddable,
			MetadataBuildingContext context) {
		try {
			typeBinder( annotationType )
					.bind( annotationType.cast( annotation ),
							context, embeddable );
		}
		catch (Exception e) {
			throw new AnnotationException(
					"Error processing @TypeBinderType annotation '%s' for embeddable type '%s'"
							.formatted( annotation, embeddable.getComponentClassName() ), e );
		}
	}

	static <A extends Annotation> void callTypeBinder(
			Annotation annotation, Class<A> annotationType,
			PersistentClass entity,
			MetadataBuildingContext context) {
		try {
			typeBinder( annotationType )
					.bind( annotationType.cast( annotation ),
							context, entity );
		}
		catch (Exception e) {
			throw new AnnotationException(
					"Error processing @TypeBinderType annotation '%s' for entity type '%s'"
							.formatted( annotation, entity.getClassName() ), e );

View on GitHub (pinned to fad1729dce)

Solutions

Inspect the exception cause chain (getCause()) - the real failure is inside your TypeBinder.bind() implementation, not in Hibernate
Step through your binder in a debugger during Metadata/SessionFactory build to find the failing line
Make the binder handle the Component (embeddable) case, not just PersistentClass/entity
Give the binder class a public no-arg constructor and verify its generic type argument matches the annotation type

Example fix

// before
public class TenantIdBinder implements TypeBinder<TenantScoped> {
    public void bind(TenantScoped ann, MetadataBuildingContext ctx, Component embeddable) {
        // NPE when the embeddable has no owner set yet
        embeddable.getOwner().getTable().addColumn( column( ann ) );
    }
}

// after
public class TenantIdBinder implements TypeBinder<TenantScoped> {
    public void bind(TenantScoped ann, MetadataBuildingContext ctx, Component embeddable) {
        if ( embeddable.getOwner() == null ) {
            throw new IllegalArgumentException(
                "@TenantScoped requires the embeddable to have an owner" );
        }
        embeddable.getOwner().getTable().addColumn( column( ann ) );
    }
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    SessionFactory sf = metadata.getSessionFactoryBuilder().build();
}
catch ( AnnotationException e ) {
    // the binder's real failure is nested - unwrap and report the cause
    Throwable cause = e.getCause() != null ? e.getCause() : e;
    throw new IllegalStateException( "Custom @TypeBinderType binder failed during bootstrap: "
        + cause.getMessage(), cause );
}

Prevention

Write a unit test that builds Metadata with only the annotated embeddable, so binder failures fail the build
Never let binder code throw bare NPEs - validate annotation attributes and metadata state and throw descriptive IllegalArgumentExceptions
Keep one binder per annotation type with a matching generic argument and a public no-arg constructor
Re-run the mapping smoke test after every Hibernate version upgrade before deploying

When it happens

Trigger: A user-defined annotation meta-annotated with @TypeBinderType is placed on an @Embeddable class. During metadata building Binders.callTypeBinder(Annotation, Class<A>, Component, MetadataBuildingContext) reflects the binder, instantiates it, and calls bind(annotation, context, embeddable); any exception from bind(), from the no-arg constructor, or from the type-argument check is caught and rethrown wrapped in this message.

Common situations: A custom TypeBinder written for entities is reused on embeddables and calls entity-only APIs; the binder dereferences null annotation attributes or an unpopulated Component; the binder class lacks a public no-arg constructor; a Hibernate upgrade changed the TypeBinder API so old binder code throws NoSuchMethodError or similar.

Related errors

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