hibernate/hibernate-orm · error · AnnotationException

Property '<propertyName>' in @IdClass '<declaringClass>' doe

Error message

Property '<propertyName>' in @IdClass '<declaringClass>' doesn't match type in entity class '<propertyType>' (expected '<entityPropertyTypeName>' but was '<idPropertyTypeName>')

What it means

Error "Property '<propertyName>' in @IdClass '<declaringClass>' doesn't match type in entity class '<propertyType>' (expected '<entityPropertyTypeName>' but was '<idPropertyTypeName>')" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/EmbeddableBinder.java:960

	private static boolean checkIdProperty(
			PropertyHolder propertyHolder, PropertyData baseInferredData,
			PropertyData entityPropertyData, PropertyData idClassPropertyData) {
		if ( entityPropertyData == null ) {
			throw new AnnotationException(
					"Property '" + getPath( propertyHolder, idClassPropertyData )
					+ "' belongs to an '@IdClass' but has no matching property in entity class '"
					+ baseInferredData.getPropertyType().getName()
					+ "' (every property of the '@IdClass' must have a corresponding persistent property in the '@Entity' class)"
			);
		}
		else if ( deferIdProperty( entityPropertyData, idClassPropertyData ) ) {
			return false;
		}
		else {
			final String idPropertyTypeName = idClassPropertyData.getTypeName();
			final String entityPropertyTypeName = entityPropertyData.getTypeName();
			if ( !hasCompatibleType( idPropertyTypeName, entityPropertyTypeName ) ) {
				throw new AnnotationException(
						"Property '" + idClassPropertyData.getPropertyName()
						+ "' in @IdClass '" + idClassPropertyData.getDeclaringClass().getName()
						+ "' doesn't match type in entity class '" + baseInferredData.getPropertyType().getName()
						+ "' (expected '" + entityPropertyTypeName + "' but was '" + idPropertyTypeName + "')"
				);
			}
			return true;
		}
	}

	//don't replace here as we need to use the actual original return type
	//the annotation overriding will be dealt with by a mechanism similar to @MapsId
	private static boolean deferIdProperty(PropertyData entityPropertyData, PropertyData idClassPropertyData) {
		return hasToOneAnnotation( entityPropertyData.getAttributeMember() )
			&& !entityPropertyData.getClassOrElementType().equals( idClassPropertyData.getClassOrElementType() );
	}

	static boolean hasCompatibleType(String typeNameInIdClass, String typeNameInEntityClass) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Change the @IdClass property type to match the entity property type exactly.

When it happens

Trigger: A composite identifier mapping (@IdClass/@EmbeddedId/@MapsId) does not match the entity's persistent properties.

Common situations: Composite primary keys where the id class properties, their types, or @MapsId values drift out of sync with the entity, or an embeddable with inheritance is reused as an id.

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