hibernate/hibernate-orm · error · AnnotationException

Target property '{}' has only {} columns which may be refere

Error message

Target property '{}' has only {} columns which may be referenced by a '@JoinColumn' for {} (each column mapped by '{}' may only occur once as a 'referencedColumnName')

What it means

Error "Target property '{}' has only {} columns which may be referenced by a '@JoinColumn' for {} (each column mapped by '{}' may only occur once as a 'referencedColumnName')" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/BinderHelper.java:528

					}
					lastPropertyColumnIndex++;
					if ( lastPropertyColumnIndex == currentProperty.getColumnSpan() ) {
						//we have exhausted the columns in this property
						currentProperty = null;
						lastPropertyColumnIndex = 0;
					}
				}
				else if ( currentProperty != null ) {
					// we didn't use up all the columns of the previous property
					throw new AnnotationException( "Target property '" + property.getName() + "' has "
							+ property.getColumnSpan() + " columns which must be referenced by a '@JoinColumn' for "
							+ associationMessage( associatedEntity, columns )
							+ " (every column mapped by '" + property.getName()
							+ "' must occur exactly once as a 'referencedColumnName', and in the correct order)" );
				}
				else if ( orderedProperties.contains( property ) ) {
					// we already used up all the columns of this property
					throw new AnnotationException( "Target property '" + property.getName() + "' has only "
							+ property.getColumnSpan() + " columns which may be referenced by a '@JoinColumn' for "
							+ associationMessage( associatedEntity, columns )
							+ " (each column mapped by '" + property.getName()
							+ "' may only occur once as a 'referencedColumnName')" );

				}
				else {
					// we have the first column of a new property
					if ( property.getColumnSpan() > 1 ) {
						if ( !property.getColumns().get(0).equals( column ) ) {
							// the columns have to occur in the right order in the property
							throw new AnnotationException("Referenced column '" + column.getName()
									+ "' mapped by target property '" + property.getName()
									+ "' occurs out of order in the list of '@JoinColumn's");
						}
						currentProperty = property;
						lastPropertyColumnIndex = 1;
					}

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the duplicate referencedColumnName; each column mapped by the target property may be referenced only once.

When it happens

Trigger: A '@JoinColumn' / 'referencedColumnName' does not line up with the columns mapped by the target entity.

Common situations: Composite foreign keys, associations to entities with secondary tables, or reordered/duplicated referencedColumnName values across multiple @JoinColumn declarations.

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