hibernate/hibernate-orm · error · MappingException

Could not create DynamicParameterizedType for type: " + type

Error message

Could not create DynamicParameterizedType for type: " + typeName

What it means

SimpleValue builds a ParameterType (DynamicParameterizedType) to hand column metadata to types like enums, @Enumerated, or custom ParameterizedType implementations. While assembling it, it must load the returned class named in the type parameters (DynamicParameterizedType.RETURNED_CLASS). When that class cannot be loaded, the ClassLoadingException is wrapped in this MappingException naming the offending typeName.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/SimpleValue.java:968

				: directAnnotationUsages.toArray( Annotation[]::new );
	}

	protected ParameterType createParameterType() {
		try {
			final int size = columns.size();
			final var columnNames = new String[size];
			final var columnLengths = new Long[size];
			for ( int i = 0; i < size; i++ ) {
				if ( columns.get(i) instanceof Column column ) {
					columnNames[i] = column.getName();
					columnLengths[i] = column.getLength();
				}
			}
			// todo : not sure this works for handling @MapKeyEnumerated
			return createParameterType( columnNames, columnLengths );
		}
		catch ( ClassLoadingException e ) {
			throw new MappingException( "Could not create DynamicParameterizedType for type: " + typeName, e );
		}
	}

	private ParameterType createParameterType(String[] columnNames, Long[] columnLengths) {
		final var attribute = (MemberDetails) typeParameters.get( DynamicParameterizedType.XPROPERTY );
		return new ParameterTypeImpl(
				classLoaderService()
						.classForTypeName( typeParameters.getProperty( DynamicParameterizedType.RETURNED_CLASS ) ),
				attribute != null ? attribute.getType() : null,
				getAnnotations( attribute ),
				table.getCatalog(),
				table.getSchema(),
				table.getName(),
				parseBoolean( typeParameters.getProperty( DynamicParameterizedType.IS_PRIMARY_KEY ) ),
				columnNames,
				columnLengths
		);
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Check the exception cause (ClassLoadingException) for the exact class name that failed, and fix the name in the @TypeDef/@Type parameters or hbm.xml <param>.
2. If the class legitimately moved, update its package in every type parameter that references it.
3. In app servers, ensure the entity/enum classes are visible to the classloader Hibernate uses (package the classes with the persistence unit, not in a sibling isolated module).
4. After renames, do a project-wide search for the old fully-qualified name in mapping resources.

Example fix

<!-- before -->
<property name="status" type="org.example.GenericEnumType">
    <param name="enumClass">com.oldpkg.Status</param>
</property>

<!-- after -->
<property name="status" type="org.example.GenericEnumType">
    <param name="enumClass">com.newpkg.Status</param>
</property>

// before building mappings, verify classes referenced by type params exist
Class<?> returned = classLoader.loadClass("com.newpkg.Status");
assert returned != null;

try {
    sessionFactory = cfg.buildSessionFactory();
} catch (MappingException e) {
    if (e.getMessage().startsWith("Could not create DynamicParameterizedType")) {
        Throwable cause = e.getCause(); // ClassLoadingException has the exact class name
        throw new IllegalStateException("Type parameter references missing class: " + cause.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: A property using a type whose type-parameters reference a class name that is not loadable in Hibernate's class loader: @Type(MyType.class) with parameters naming a moved/renamed class, hbm.xml <type name="..."><param name="returnedClass">bad.Foo</param></type>, or @Enumerated where the enum class was renamed or lives in a module invisible to the ORM classloader.

Common situations: Refactoring that renames or moves an enum or custom BasicType without updating hbm.xml or @TypeDef parameters; fat WAR/classloader isolation in application servers where Hibernate's classloader cannot see the app class; stale compiled mappings after upgrades; copy-pasted param values with wrong package names.

Related errors

• Can't load class: {}
• Could not resolve named type: {}
• Class '<componentClassName>' is an '@Embeddable' type and ma
• Property '<propertyName>' may not be annotated '@BatchSize'
• One to many association '<propertyName>' was annotated '@Col

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