hibernate/hibernate-orm · error · AnnotationException

An association that targets entity '" + referencedEntity.get

Error message

An association that targets entity '" + referencedEntity.getEntityName() + "' from entity '" + associatedClass.getEntityName() + "' has " + joinColumns.getColumns().size() + " '@JoinColumn's but the primary key has " + referencedEntity.getIdentifier().getColumnSpan() + " columns"

What it means

Error "An association that targets entity '" + referencedEntity.getEntityName() + "' from entity '" + associatedClass.getEntityName() + "' has " + joinColumns.getColumns().size() + " '@JoinColumn's but the primary key has " + referencedEntity.getIdentifier().getColumnSpan() + " columns"" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/TableBinder.java:633

				bindNonPrimaryKeyReference( referencedEntity, joinColumns, value );
				break;
			case IMPLICIT_PRIMARY_KEY_REFERENCE:
				bindImplicitPrimaryKeyReference( referencedEntity, joinColumns, value, associatedClass );
				break;
			case EXPLICIT_PRIMARY_KEY_REFERENCE:
				bindPrimaryKeyReference( referencedEntity, joinColumns, value, associatedClass, buildingContext );
				break;
		}
	}

	private static void bindImplicitPrimaryKeyReference(
			PersistentClass referencedEntity,
			AnnotatedJoinColumns joinColumns,
			SimpleValue value,
			PersistentClass associatedClass) {
		//implicit case, we hope PK and FK columns are in the same order
		if ( joinColumns.getColumns().size() != referencedEntity.getIdentifier().getColumnSpan() ) {
			throw new AnnotationException(
					"An association that targets entity '" + referencedEntity.getEntityName()
							+ "' from entity '" + associatedClass.getEntityName()
							+ "' has " + joinColumns.getColumns().size() + " '@JoinColumn's but the primary key has "
							+ referencedEntity.getIdentifier().getColumnSpan() + " columns"
			);
		}
		linkJoinColumnWithValueOverridingNameIfImplicit(
				referencedEntity,
				referencedEntity.getIdentifier(),
				joinColumns,
				value
		);
		if ( value instanceof SortableValue sortableValue ) {
			sortableValue.sortProperties();
		}
	}

	private static void bindPrimaryKeyReference(

View on GitHub (pinned to fad1729dce)

Solutions

1. Add or remove @JoinColumn entries so their count matches the primary key column count of the target entity.

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/96ad1385292c7582. Report an issue: GitHub.