hibernate/hibernate-orm · error · AnnotationException

Association '{}' is 'mappedBy' another entity and may not sp

Error message

Association '{}' is 'mappedBy' another entity and may not specify a '@MapKeyColumn' (use '@MapKey' instead)

What it means

Error "Association '{}' is 'mappedBy' another entity and may not specify a '@MapKeyColumn' (use '@MapKey' instead)" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java:1214

				throw new AnnotationException( "Association '"
						+ qualify( propertyHolder.getPath(), propertyName )
						+ "' is 'mappedBy' another entity and may not specify the '@JoinTable'" );
			}
			if ( oneToMany ) {
				if ( property.hasDirectAnnotationUsage( MapKeyColumn.class ) ) {
					BOOT_LOGGER.mappedByShouldNotSpecifyMapKeyColumn(
							qualify( propertyHolder.getPath(), propertyName )
					);
				}
				if ( property.hasDirectAnnotationUsage( OrderColumn.class ) ) {
					BOOT_LOGGER.mappedByShouldNotSpecifyOrderColumn(
							qualify( propertyHolder.getPath(), propertyName )
					);
				}
			}
			else {
				if ( property.hasDirectAnnotationUsage( MapKeyColumn.class ) ) {
					throw new AnnotationException( "Association '"
							+ qualify( propertyHolder.getPath(), propertyName )
							+ "' is 'mappedBy' another entity and may not specify a '@MapKeyColumn'"
							+ " (use '@MapKey' instead)" );
				}
				if ( property.hasDirectAnnotationUsage( OrderColumn.class ) ) {
					throw new AnnotationException( "Association '"
							+ qualify( propertyHolder.getPath(), propertyName )
							+ "' is 'mappedBy' another entity and may not specify an '@OrderColumn'"
							+ " (use '@OrderBy' instead)" );
				}
			}
		}
		else if ( oneToMany
				&& property.hasDirectAnnotationUsage( OnDelete.class )
				&& !hasExplicitJoinColumn() ) {
			throw new AnnotationException( "Unidirectional '@OneToMany' association '"
					+ qualify( propertyHolder.getPath(), propertyName )
					+ "' is annotated '@OnDelete' and must explicitly specify a '@JoinColumn'" );

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove @MapKeyColumn from the mappedBy side and use @MapKey instead, as instructed.

When it happens

Trigger: An association declares 'mappedBy' naming a property that does not exist, has the wrong type, or is not the owning side on the target entity.

Common situations: Bidirectional associations where mappedBy is misspelled, both sides claim ownership, or the target entity was refactored without updating the mapping.

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