hibernate/hibernate-orm · error · MappingException

'@CollectionType' [" + role + "] specified parameters, but t

Error message

'@CollectionType' [" + role + "] specified parameters, but the implementation '" + implementation.getName() + "' does not implement 'ParameterizedType' which is used to inject them

What it means

MappingHelper throws when a @CollectionType custom collection implementation was given parameters, but the implementation class does not implement org.hibernate.usertype.ParameterizedType - the interface Hibernate uses to inject those parameter values.

Source

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

						.getBean( userCollectionTypeClass );
		if ( isNotEmpty( parameters ) ) {
			if ( ParameterizedType.class.isAssignableFrom( managedBean.getBeanClass() ) ) {
				// create a copy of the parameters and create a bean wrapper to delay injecting
				// the parameters, thereby delaying the need to resolve the instance from the
				// wrapped bean
				final var copy = new Properties();
				copy.putAll( parameters );
				return new DelayedParameterizedTypeBean<>( managedBean, copy );
			}
			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) {

View on GitHub (pinned to fad1729dce)

Solutions

Implement org.hibernate.usertype.ParameterizedType on the collection type class (override setParameterValues(Properties)) and consume the parameters.
Or remove the parameters from the @CollectionType declaration if they are unused.
If per-collection configuration is required without ParameterizedType, use a distinct implementation class per configuration.

Example fix

// before
public class MyCollectionType implements UserCollectionType { ... }

@CollectionType(implementation = MyCollectionType.class,
                parameters = @Param(name = "k", value = "v"))
List<Item> items;

// after
public class MyCollectionType implements UserCollectionType, ParameterizedType {
    @Override
    public void setParameterValues(Properties parameters) { ... }
}

Defensive patterns

Strategy: validation

Validate before calling

static boolean acceptsParameters(Class<? extends UserCollectionType> impl) {
    return org.hibernate.usertype.ParameterizedType.class.isAssignableFrom(impl);
}

Prevention

Make ParameterizedType part of the base class for all custom collection types.
Only pass @Param values to implementations designed to read them.
Cover custom collection types with mapping tests that build Metadata.

When it happens

Trigger: @CollectionType(implementation = X.class, parameters = @Param(...)) where X does not implement ParameterizedType; hbm <collection-type ...><param>...</param></collection-type> with the same problem; porting a UserCollectionType that never needed parameters into a mapping that now supplies them.

Common situations: Adding parameters to an existing custom collection type; copy-pasting @CollectionType declarations between collections; upgrading mappings to push configuration into collection types.

Related errors

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