hibernate/hibernate-orm · error · AnnotationException

Association {} has a '@JoinColumn' which does not specify th

Error message

Association {} has a '@JoinColumn' which does not specify the 'referencedColumnName' (when an association has multiple '@JoinColumn's, they must each specify their 'referencedColumnName')

What it means

Error "Association {} has a '@JoinColumn' which does not specify the 'referencedColumnName' (when an association has multiple '@JoinColumn's, they must each specify their 'referencedColumnName')" thrown in hibernate/hibernate-orm.

Source

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

		clone.setValue( property.getValue() );
		return clone;
	}

	private static List<Property> findPropertiesByColumns(
			AttributeContainer columnOwner,
			AnnotatedJoinColumns columns,
			PersistentClass associatedEntity,
			MetadataBuildingContext context) {

		// Build the list of column names in the exact order they were
		// specified by the @JoinColumn annotations.
		final List<Column> orderedColumns = new ArrayList<>( columns.getJoinColumns().size() );
		final Map<Column, Set<Property>> columnsToProperty = new HashMap<>();
		final var collector = context.getMetadataCollector();
		final var referencedTable = columnOwner.getTable();
		for ( var joinColumn : columns.getJoinColumns() ) {
			if ( joinColumn.isReferenceImplicit() ) {
				throw new AnnotationException( "Association " + associationMessage( associatedEntity, columns )
						+ " has a '@JoinColumn' which does not specify the 'referencedColumnName'"
						+ " (when an association has multiple '@JoinColumn's, they must each specify their 'referencedColumnName')");
			}
			final String name = collector.getPhysicalColumnName( referencedTable, joinColumn.getReferencedColumn() );
			final var column = new Column( name );
			orderedColumns.add( column );
			columnsToProperty.put( column, new LinkedHashSet<>() ); //need to use a LinkedHashSet here to make it deterministic
		}

		// Now, for each column find the properties of the target entity
		// which are mapped to that column. (There might be multiple such
		// properties for each column.)
		if ( columnOwner instanceof PersistentClass persistentClass ) {
			// Process ToOne associations after Components, Basic and Id properties
			final List<Property> toOneProperties = new ArrayList<>();
			for ( var property : persistentClass.getReferenceableProperties() ) {
				if ( property.getValue() instanceof ToOne ) {
					toOneProperties.add( property );

View on GitHub (pinned to fad1729dce)

Solutions

1. Add referencedColumnName to every @JoinColumn of the association when more than one join column is used.

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/6d28be1b4a984627. Report an issue: GitHub.