hibernate/hibernate-orm · error · MappingException

'UserType' implementation '" + type.getClass().getName() + "

Error message

'UserType' implementation '" + type.getClass().getName() + "' does not implement 'ParameterizedType' or 'AnnotationBasedUserType' but parameters were provided

What it means

MappingHelper#injectParameters throws when a custom UserType receives non-empty parameters but implements neither ParameterizedType (to receive them programmatically) nor AnnotationBasedUserType (to receive the annotation instance). The parameters simply have nowhere to go.

Source

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

			else {
				throwIgnoredCollectionTypeParameters( role, userCollectionTypeClass );
			}
		}
		return managedBean;
	}

	private static void throwIgnoredCollectionTypeParameters(String role, Class<?> implementation) {
		throw new MappingException( "'@CollectionType' [" + role + "] specified parameters, but the implementation '"
				+ implementation.getName() + "' does not implement 'ParameterizedType' which is used to inject them" );
	}

	public static void injectParameters(Object type, Properties parameters) {
		if ( type instanceof ParameterizedType parameterizedType ) {
			parameterizedType.setParameterValues( parameters == null ? EMPTY_PROPERTIES : parameters );
		}
		else if ( parameters != null && !parameters.isEmpty()
				&& !( type instanceof AnnotationBasedUserType<?,?> ) ) {
			throw new MappingException( "'UserType' implementation '" + type.getClass().getName()
					+ "' does not implement 'ParameterizedType' or 'AnnotationBasedUserType' but parameters were provided" );
		}
	}

	private static ManagedBean<UserCollectionType> createLocalUserTypeBean(
			String role,
			Class<? extends UserCollectionType> implementation,
			Map<String, ?> parameters) {
		final var userCollectionType =
				FallbackBeanInstanceProducer.INSTANCE.produceBeanInstance( implementation );
		if ( isNotEmpty( parameters ) ) {
			// CollectionType declared parameters - inject them
			if ( userCollectionType instanceof ParameterizedType parameterizedType ) {
				final var properties = new Properties();
				properties.putAll( parameters );
				parameterizedType.setParameterValues( properties );
			}
			else {

View on GitHub (pinned to fad1729dce)

Solutions

Implement org.hibernate.usertype.ParameterizedType on the UserType (setParameterValues) and consume the parameters.
Or extend AnnotationBasedUserType to read configuration from the annotation instance itself.
Or delete the parameters - they cannot reach a type that accepts none.

Example fix

// before
@Type(value = MyStringType.class,
      parameters = @Param(name = "k", value = "v"))
private String note; // MyStringType implements only UserType

// after
public class MyStringType implements UserType<String>, ParameterizedType {
    @Override
    public void setParameterValues(Properties parameters) { ... }
}

Defensive patterns

Strategy: validation

Validate before calling

static boolean userTypeAcceptsParameters(UserType<?> type) {
    return type instanceof org.hibernate.usertype.ParameterizedType
            || type instanceof AnnotationBasedUserType;
}

Prevention

Implement ParameterizedType in the base class of every custom UserType that may be configured.
Only attach @Param parameters to types that declare they consume them.
Use AnnotationBasedUserType when configuration should come from the annotation itself.

When it happens

Trigger: @Type(value = X.class, parameters = @Param(...)) or hbm <type name="X"><param>...</param></type> where X is a plain UserType; migrating parameterized hbm types to annotations; adding <param> entries to an existing type that ignores them.

Common situations: Legacy UserType implementations that predate parameter support; supplying configuration (enum prefix, varchar length, format) to a type that was not built to read it.

Related errors

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