hibernate/hibernate-orm · error · MappingException

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

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.

Solutions

1. Implement org.hibernate.usertype.ParameterizedType on the collection type class (override setParameterValues(Properties)) and consume the parameters.
2. Or remove the parameters from the @CollectionType declaration if they are unused.
3. 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) { ... }
}

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

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

• 'UserType' implementation '" + type.getClass().getName() +…
• Ambiguous persistent property methods declared by
• An association from the table '" + getTable().getName() +…
• An association from the table '" + getTable().getName() +…
• <any name=" " /> mapping needs to specify 2 or more columns

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

Appendix: 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)