hibernate/hibernate-orm · error · AnnotationException

Unidirectional '@OneToMany' association '<path>' is annotate

Error message

Unidirectional '@OneToMany' association '<path>' is annotated '@OnDelete' and must explicitly specify a '@JoinColumn'

What it means

Error "Unidirectional '@OneToMany' association '<path>' is annotated '@OnDelete' and must explicitly specify a '@JoinColumn'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/CollectionBinder.java:1230

			else {
				if ( property.hasDirectAnnotationUsage( MapKeyColumn.class ) ) {
					throw new AnnotationException( "Association '"
							+ qualify( propertyHolder.getPath(), propertyName )
							+ "' is 'mappedBy' another entity and may not specify a '@MapKeyColumn'"
							+ " (use '@MapKey' instead)" );
				}
				if ( property.hasDirectAnnotationUsage( OrderColumn.class ) ) {
					throw new AnnotationException( "Association '"
							+ qualify( propertyHolder.getPath(), propertyName )
							+ "' is 'mappedBy' another entity and may not specify an '@OrderColumn'"
							+ " (use '@OrderBy' instead)" );
				}
			}
		}
		else if ( oneToMany
				&& property.hasDirectAnnotationUsage( OnDelete.class )
				&& !hasExplicitJoinColumn() ) {
			throw new AnnotationException( "Unidirectional '@OneToMany' association '"
					+ qualify( propertyHolder.getPath(), propertyName )
					+ "' is annotated '@OnDelete' and must explicitly specify a '@JoinColumn'" );
		}
	}

	private boolean hasExplicitJoinColumn() {
		return property.hasDirectAnnotationUsage( JoinColumn.class )
			|| property.hasDirectAnnotationUsage( JoinColumns.class )
			|| property.hasDirectAnnotationUsage( JoinTable.class )
			&& property.getDirectAnnotationUsage( JoinTable.class )
						.joinColumns().length > 0;
	}

	private void bindProperty() {
		//property building
		final var binder = new PropertyBinder();
		binder.setName( propertyName );
		binder.setValue( collection );

View on GitHub (pinned to fad1729dce)

Solutions

1. Add an explicit @JoinColumn to the unidirectional @OneToMany annotated @OnDelete.
2. Or remove @OnDelete from the association.

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