hibernate/hibernate-orm · error · AnnotationException

Empty '@PrimaryKeyJoinColumns' annotation

Error message

Empty '@PrimaryKeyJoinColumns' annotation

What it means

Error "Empty '@PrimaryKeyJoinColumns' annotation" thrown in hibernate/hibernate-orm.

Source

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

				case JOINED -> new JoinedSubclass( superEntity, metadataBuildingContext );
				case TABLE_PER_CLASS -> new UnionSubclass( superEntity, metadataBuildingContext );
			};
		}
	}

	private static AnnotatedJoinColumns subclassJoinColumns(
			ClassDetails clazzToProcess,
			PersistentClass superEntity,
			MetadataBuildingContext context) {
		//@Inheritance(JOINED) subclass need to link back to the super entity
		final var joinColumns = new AnnotatedJoinColumns();
		joinColumns.setBuildingContext( context );
		final var modelsContext = context.getBootstrapContext().getModelsContext();
		if ( clazzToProcess.hasAnnotationUsage( PrimaryKeyJoinColumn.class, modelsContext ) ) {
			final var columns = clazzToProcess.getRepeatedAnnotationUsages( PrimaryKeyJoinColumn.class, modelsContext );
			if ( columns.length == 0 ) {
				// PrimaryKeyJoinColumns must not be empty according to Javadoc
				throw new AnnotationException( "Empty '@PrimaryKeyJoinColumns' annotation" );
			}
			for ( var column : columns ) {
				buildInheritanceJoinColumn(
						column,
						null,
						superEntity.getIdentifier(),
						joinColumns,
						context
				);
			}
		}
		else {
			buildInheritanceJoinColumn(
					null,
					null,
					superEntity.getIdentifier(),
					joinColumns,
					context

View on GitHub (pinned to fad1729dce)

Solutions

1. Add at least one @PrimaryKeyJoinColumn inside @PrimaryKeyJoinColumns, or remove the empty annotation.

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