hibernate/hibernate-orm · error · AnnotationException

Property '<propertyName>' of entity '<entityName>' must have

Error message

Property '<propertyName>' of entity '<entityName>' must have a '@JoinColumn' which references the foreign key column '<logicalColumnName>'

What it means

Error "Property '<propertyName>' of entity '<entityName>' must have a '@JoinColumn' which references the foreign key column '<logicalColumnName>'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/EmbeddableBinder.java:1358

						buildingContext.getBuildingOptions().getPhysicalNamingStrategy();
				final var database = buildingContext.getMetadataCollector().getDatabase();
				for ( var selectable : referencedValue.getSelectables() ) {
					if ( selectable instanceof org.hibernate.mapping.Column column ) {
						final AnnotatedJoinColumn joinColumn;
						final String logicalColumnName;
						final String referenceName;
						if ( isExplicitReference ) {
							logicalColumnName = column.getName();
							referenceName = normalizedColumnName( column );
						}
						else {
							logicalColumnName = null;
							referenceName = String.valueOf( index.get() );
							index.getAndIncrement();
						}
						joinColumn = columnByReferencedName.get( referenceName );
						if ( joinColumn == null && !firstColumn.isNameDeferred() ) {
							throw new AnnotationException(
									"Property '" + propertyName
									+ "' of entity '" + embeddable.getOwner().getEntityName()
									+ "' must have a '@JoinColumn' which references the foreign key column '"
									+ logicalColumnName + "'"
							);
						}
						final String columnName =
								joinColumn == null || joinColumn.isNameDeferred()
										? "tata_" + column.getName()
										: joinColumn.getName();

						final String physicalName =
								physicalNamingStrategy
										.toPhysicalColumnName( database.toIdentifier( columnName ),
												database.getJdbcEnvironment() )
										.render( database.getDialect() );
						value.addColumn( new org.hibernate.mapping.Column( physicalName ) );
						if ( joinColumn != null ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Add a @JoinColumn on the property referencing the required foreign key column.

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