hibernate/hibernate-orm · error · AnnotationException

Missing 'value' in '@MapsId' annotation of association '<pro

Error message

Missing 'value' in '@MapsId' annotation of association '<propertyName>' of entity '<entityName>' with composite identifier type ('@MapsId' must specify a property of the '@EmbeddedId' class which has the foreign key of '<referencedEntityName>')

What it means

Error "Missing 'value' in '@MapsId' annotation of association '<propertyName>' of entity '<entityName>' with composite identifier type ('@MapsId' must specify a property of the '@EmbeddedId' class which has the foreign key of '<referencedEntityName>')" thrown in hibernate/hibernate-orm.

Source

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

						referencedProperty
				);
			}
		}

		private Component getReferencedComponent(PersistentClass referencedPersistentClass) {
			if ( referencedPersistentClass == null ) {
				// TODO: much better error message if this is something that can really happen!
				throw new AnnotationException( "Unknown entity name '" + referencedEntityName + "'");
			}
			if ( referencedPersistentClass.getIdentifier() instanceof Component id ) {
				return id;
			}
			else {
				// The entity with the @MapsId annotation has a composite
				// id type, but the referenced entity has a basic-typed id.
				// Therefore, the @MapsId annotation should have specified
				// a property of the composite id that has the foreign key
				throw new AnnotationException(
						"Missing 'value' in '@MapsId' annotation of association '" + propertyName
						+ "' of entity '" + embeddable.getOwner().getEntityName()
						+ "' with composite identifier type"
						+ " ('@MapsId' must specify a property of the '@EmbeddedId' class which has the foreign key of '"
						+ referencedEntityName + "')"
				);
			}
		}

		private Property createComponentProperty(
				boolean isExplicitReference,
				Map<String, AnnotatedJoinColumn> columnByReferencedName,
				MutableInteger index,
				Property referencedProperty ) {
			final var property = new Property();
			property.setName( referencedProperty.getName() );
			//FIXME set optional?
			//property.setOptional( property.isOptional() );

View on GitHub (pinned to fad1729dce)

Solutions

1. Set @MapsId(value=...) to the property of the @EmbeddedId class holding the foreign key.

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/0155cf3f226569f6. Report an issue: GitHub.