hibernate/hibernate-orm · error · AnnotationException

The '@JoinColumn' for a secondary table must reference the p

Error message

The '@JoinColumn' for a secondary table must reference the primary key

What it means

Error "The '@JoinColumn' for a secondary table must reference the primary key" thrown in hibernate/hibernate-orm.

Source

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

	private static void bindNonPrimaryKeyReference(
			PersistentClass referencedEntity,
			AnnotatedJoinColumns joinColumns,
			SimpleValue value) {
		final String referencedPropertyName;
		if ( value instanceof ToOne toOne ) {
			referencedPropertyName = toOne.getReferencedPropertyName();
		}
		else if ( value instanceof DependantValue ) {
			final String propertyName = joinColumns.getPropertyName();
			if ( propertyName != null ) {
				final var collection = (Collection)
						referencedEntity.getRecursiveProperty( propertyName )
								.getValue();
				referencedPropertyName = collection.getReferencedPropertyName();
			}
			else {
				throw new AnnotationException( "The '@JoinColumn' for a secondary table must reference the primary key" );
			}
		}
		else {
			throw new AssertionFailure( "Property ref to an unexpected Value type: " + value.getClass().getName() );
		}
		if ( referencedPropertyName == null ) {
			throw new AssertionFailure( "No property ref found" );
		}

		final var synthProp = referencedEntity.getReferencedProperty( referencedPropertyName );
		if ( synthProp == null ) {
			throw new AssertionFailure( "Cannot find synthetic property: "
					+ referencedEntity.getEntityName() + "." + referencedPropertyName );
		}
		linkJoinColumnWithValueOverridingNameIfImplicit( referencedEntity, synthProp.getValue(), joinColumns, value );
		checkReferenceToUniqueKey( value, synthProp );
		( (SortableValue) value ).sortProperties();
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Make the secondary table @JoinColumn reference the primary key column of the main table.

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/3a50603c2cf7cdde. Report an issue: GitHub.