hibernate/hibernate-orm · error · AnnotationException

Property '<path>' belongs to an '@IdClass' but has no matchi

Error message

Property '<path>' belongs to an '@IdClass' but has no matching property in entity class '<propertyType>' (every property of the '@IdClass' must have a corresponding persistent property in the '@Entity' class)

What it means

Error "Property '<path>' belongs to an '@IdClass' but has no matching property in entity class '<propertyType>' (every property of the '@IdClass' must have a corresponding persistent property in the '@Entity' class)" thrown in hibernate/hibernate-orm.

Source

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

		final Map<String, PropertyData> baseClassElementsByName = new HashMap<>();
		for ( var element : baseClassElements ) {
			baseClassElementsByName.put( element.getPropertyName(), element );
		}
		for ( int i = 0; i < classElements.size(); i++ ) {
			final var idClassPropertyData = classElements.get( i );
			final var entityPropertyData = baseClassElementsByName.get( idClassPropertyData.getPropertyName() );
			if ( !propertyHolder.isInIdClass()
					|| checkIdProperty( propertyHolder, baseInferredData, entityPropertyData, idClassPropertyData ) ) {
				classElements.set( i, entityPropertyData );  //this works since they are in the same order
			}
		}
	}

	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 + "')"

View on GitHub (pinned to fad1729dce)

Solutions

1. Add a matching persistent property to the entity class for every property of the @IdClass.
2. Or remove the unmatched property from the @IdClass.

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/08dd22a3eb78113f. Report an issue: GitHub.