hibernate/hibernate-orm · error · MappingException

Error calling Value#setTypeUsingReflection: containingClassN

Error message

Error calling Value#setTypeUsingReflection: containingClassName=[%s], propertyName=[%s], role=[%s]

What it means

The reflection-based type resolution did run, but Value.setTypeUsingReflection(containingClassName, propertyName) threw a MappingException - typically because the named class does not exist on the classpath, has no field/getter named propertyName, or the property's Java type has no resolvable Hibernate type. The original exception is chained, so the cause carries the precise reason.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java:2185

			Value value,
			String containingClassName,
			String propertyName,
			AttributeRole attributeRole) {
		if ( StringHelper.isEmpty( propertyName ) ) {
			throw new MappingException(
					"Attribute mapping must define a name attribute:"
					+ " containingClassName=[%s], propertyName=[%s], role=[%s]"
							.formatted( containingClassName, propertyName,
									attributeRole.getFullPath() ),
					sourceDocument.getOrigin()
			);
		}

		try {
			value.setTypeUsingReflection( containingClassName, propertyName );
		}
		catch (MappingException ome) {
			throw new MappingException(
					"Error calling Value#setTypeUsingReflection:"
					+ " containingClassName=[%s], propertyName=[%s], role=[%s]"
							.formatted( containingClassName, propertyName,
									attributeRole.getFullPath() ),
					ome,
					sourceDocument.getOrigin()
			);
		}
	}

	private void bindProperty(
			MappingDocument mappingDocument,
			AttributeSource propertySource,
			Property property) {
		property.setName( propertySource.getName() );

		final String propertyAccessorName = propertySource.getPropertyAccessorName();
		property.setPropertyAccessorName( isNotEmpty( propertyAccessorName )

View on GitHub (pinned to fad1729dce)

Solutions

Read the chained cause: ClassNotFoundException means fix class=; PropertyNotFoundException means align name= with the actual field/getter
If the Java type has no default Hibernate type, add an explicit type attribute or register a UserType/CompositeUserType
Ensure the mapped class is on the application classpath at bootstrap time

Example fix

// before
<property name='email' column='email'/>  <!-- field renamed to emailAddress -->

// after
<property name='emailAddress' column='email'/>

Defensive patterns

Strategy: validation

Validate before calling

// verify class + property exist before Hibernate reflects
Class<?> clazz = Class.forName(mappingClassName);
PropertyDescriptor[] props = Introspector.getBeanInfo(clazz).getPropertyDescriptors();
boolean found = Arrays.stream(props).anyMatch(p -> p.getName().equals(propertyName) && p.getReadMethod() != null);
if (!found) {
    throw new IllegalStateException("No readable property '" + propertyName + "' on " + mappingClassName);
}

Type guard

static boolean hasReadableProperty(Class<?> clazz, String name) {
    try {
        return new PropertyDescriptor(name, clazz).getReadMethod() != null;
    } catch (IntrospectionException e) {
        return false;
    }
}

Try / catch

catch (MappingException e) during bootstrap and log getCause() - the cause distinguishes ClassNotFoundException (fix class=) from PropertyNotFoundException (align name=). Fix the mapping; retrying cannot help.

Prevention

Rename Java fields and mapping names in the same change
Keep mapped classes on the runtime classpath (verify with Class.forName in tests)
Specify explicit types for exotic Java types or register a UserType

When it happens

Trigger: class= pointing to a class not on the classpath; name= pointing to a field/getter that does not exist or was renamed; a property whose Java type has no registered Hibernate type and no explicit type attribute was given.

Common situations: Renaming a Java field without updating the mapping; mapping files referencing classes from a jar missing at runtime; custom value types needing an explicit type, UserType, or CompositeUserType that was not declared.

Related errors

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