What causes "Class '" + typeName + "' does not implement '" + supertype.getName() + "'" in hibernate/hibernate-orm?

Open the named class, determine which Hibernate interface the mapping position requires, and implement that interface.

hibernate/hibernate-orm · error · MappingException

Class '" + typeName + "' does not implement '" + supertype.g

Error message

Class '" + typeName + "' does not implement '" + supertype.getName() + "'

What it means

MappingHelper#classForName(supertype, ...) loads a class by name and verifies it is assignable to the required Hibernate interface (UserCollectionType, UserType and similar strategy contracts). This MappingException means the named class exists and loads, but does not implement the interface demanded by the mapping position it was declared in.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/MappingHelper.java:128

		for ( var property : properties ) {
			if ( ( property.isUpdatable() || property.isInsertable() ) && !property.isGenericSpecialization() ) {
				property.getValue().checkColumnDuplication( distinctColumns, owner );
			}
		}
	}

	static Class<?> classForName(String typeName, BootstrapContext bootstrapContext) {
		return bootstrapContext.getClassLoaderAccess().classForName( typeName );
	}

	static <T> Class<? extends T> classForName(Class<T> supertype, String typeName, BootstrapContext bootstrapContext) {
		final var clazz = classForName( typeName, bootstrapContext );
		if ( supertype.isAssignableFrom( clazz ) ) {
			//noinspection unchecked
			return (Class<? extends T>) clazz;
		}
		else {
			throw new MappingException( "Class '" + typeName + "' does not implement '" + supertype.getName() + "'" );
		}
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Open the named class, determine which Hibernate interface the mapping position requires, and implement that interface.
Or move the declaration to the position matching the interface the class does implement.
Verify you did not reference the wrong class - e.g. the handled Java type instead of the UserType implementation.

Example fix

<!-- before -->
<collection-type name="com.acme.MyList"/> <!-- MyList does not implement UserCollectionType -->

<!-- after -->
public class MyList implements UserCollectionType { ... }
<collection-type name="com.acme.MyList"/>

Defensive patterns

Strategy: validation

Validate before calling

static <T> boolean implementsContract(Class<T> contract, String className)
        throws ClassNotFoundException {
    return contract.isAssignableFrom(
        Class.forName(className, false, Thread.currentThread().getContextClassLoader()));
}

Prevention

Keep one type class per extension point; never reuse a UserType as a collection type or vice versa.
Pass Class references (annotations) instead of string names so mismatches surface earlier.
Smoke-test all custom types by building Metadata at startup.

When it happens

Trigger: An hbm <collection-type name="X"> where X does not implement UserCollectionType; a <type name="X"> used where a CompositeUserType (or another contract) is required; accidentally naming the domain class or enum instead of the type implementation class.

Common situations: Custom types first wired into the wrong extension point; refactoring a UserType into a UserCollectionType or back; copy-paste of type declarations between mapping positions.

Related errors

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