hibernate/hibernate-orm · error · AnnotationException

Map key property '${property}' not found in target entity '$

Error message

Map key property '${property}' not found in target entity '${entity}'

What it means

Error "Map key property '${property}' not found in target entity '${entity}'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/MapBinder.java:274

		//target has priority over reflection for the map key type
		//JPA 2 has priority
		final var mapKeyClassAnn = property.getDirectAnnotationUsage( MapKeyClass.class );
		final var target = mapKeyClassAnn != null ? mapKeyClassAnn.value() : void.class;
		return void.class.equals( target ) ? property.getMapKeyType().getName() : target.getName();
	}

	private void handleMapKeyProperty(
			TypeDetails elementType,
			java.util.Map<String, PersistentClass> persistentClasses,
			String mapKeyPropertyName) {
		final var associatedClass = persistentClasses.get( elementType.getName() );
		if ( associatedClass == null ) {
			throw new AnnotationException( "Association '" + safeCollectionRole() + "'"
					+ targetEntityMessage( elementType ) );
		}
		final Property mapProperty = findPropertyByName( associatedClass, mapKeyPropertyName );
		if ( mapProperty == null ) {
			throw new AnnotationException( "Map key property '" + mapKeyPropertyName
					+ "' not found in target entity '" + associatedClass.getEntityName() + "'" );
		}
		// HHH-11005 - if InheritanceType.JOINED then need to find class defining the column
		final var targetEntity =
				inheritanceStatePerClass.get( elementType.determineRawClass() ).getType() == InheritanceType.JOINED
						? mapProperty.getPersistentClass()
						: associatedClass;
		final Value indexValue =
				createFormulatedValue( mapProperty.getValue(), collection, associatedClass, targetEntity );
		getMap().setIndex( indexValue );
		getMap().setMapKeyPropertyName( mapKeyPropertyName );
	}

	private CollectionPropertyHolder buildCollectionPropertyHolder(
			MemberDetails property,
			TypeDetails keyClass) {
		return buildCollectionPropertyHolder( property, keyClass.determineRawClass() );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Correct the map key property name to an existing property of the target entity.

When it happens

Trigger: A @MapKey names a property that does not exist on the target entity of the map.

Common situations: Map-valued associations whose @MapKey property was renamed or removed on the target entity, or a typo in the property name.

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