hibernate/hibernate-orm · error · AnnotationException

Entity class '<className>' may not specify a '@PrimaryKeyJoi

Error message

Entity class '<className>' may not specify a '@PrimaryKeyJoinColumn'

What it means

Error "Entity class '<className>' may not specify a '@PrimaryKeyJoinColumn'" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/EntityBinder.java:967

			// let's see if we had a discriminator column (it's perfectly
			// valid for joined inheritance to not have a discriminator)
			if ( discriminatorColumn != null ) {
				// we do have a discriminator column
				if ( state.hasSiblings() || !discriminatorColumn.isImplicit() ) {
					final var rootClass = (RootClass) persistentClass;
					bindDiscriminatorColumnToRootPersistentClass( rootClass, discriminatorColumn, holder );
					if ( context.getBuildingOptions().shouldImplicitlyForceDiscriminatorInSelect() ) {
						rootClass.setForceDiscriminator( true );
					}
				}
			}
		}
	}

	private void checkNoJoinColumns(ClassDetails annotatedClass) {
		if ( annotatedClass.hasAnnotationUsage( PrimaryKeyJoinColumns.class, modelsContext() )
				|| annotatedClass.hasAnnotationUsage( PrimaryKeyJoinColumn.class, modelsContext() ) ) {
			throw new AnnotationException( "Entity class '" + annotatedClass.getName()
					+ "' may not specify a '@PrimaryKeyJoinColumn'" );
		}
	}

	private void checkNoOnDelete(ClassDetails annotatedClass) {
		if ( annotatedClass.hasAnnotationUsage( PrimaryKeyJoinColumns.class, modelsContext() )
				|| annotatedClass.hasAnnotationUsage( PrimaryKeyJoinColumn.class, modelsContext() ) ) {
			throw new AnnotationException( "Entity class '" + annotatedClass.getName() + "' may not be annotated '@OnDelete'" );
		}
	}

	private static void handleForeignKey(ClassDetails clazzToProcess, MetadataBuildingContext context, DependantValue key) {
		final var foreignKey = clazzToProcess.getDirectAnnotationUsage( ForeignKey.class );
		handleForeignKeyConstraint( key, foreignKey, nestedForeignKey( clazzToProcess ), context );
	}

	private static ForeignKey nestedForeignKey(ClassDetails clazzToProcess) {
		final var pkJoinColumn = clazzToProcess.getDirectAnnotationUsage( PrimaryKeyJoinColumn.class );

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove @PrimaryKeyJoinColumn from the entity class where it is not permitted.

When it happens

Trigger: A primary-key join column declaration is empty, misplaced, or does not reference the primary key.

Common situations: Empty @PrimaryKeyJoinColumns, @PrimaryKeyJoinColumn on a class that forbids it, or a secondary-table join not referencing the primary key.

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/07e3341fca225cbc. Report an issue: GitHub.