hibernate/hibernate-orm · error · MappingException

Could not create DynamicParameterizedType for 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.

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
• A '@JoinColumn' references a column named
• all @TenantId fields must have the same type
• Annotation ' ' is not assignable to

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

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