hibernate/hibernate-orm · error · HibernateException

Primary key referenced an unknown entity: {}

Error message

Primary key referenced an unknown entity: {}

What it means

Error "Primary key referenced an unknown entity: {}" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:1788

			secondPasses.clear();
		}
	}

	private void processFkSecondPassesInOrder() {
		if ( fkSecondPassList == null || fkSecondPassList.isEmpty() ) {
			processSecondPasses( secondaryTableFromAnnotationSecondPassesList );
		}
		else {
			// split FkSecondPass instances into primary key and non primary key FKs.
			// While doing so build a map of class names to FkSecondPass instances depending on this class.
			final Map<String, Set<FkSecondPass>> isADependencyOf = new HashMap<>();
			final List<FkSecondPass> endOfQueueFkSecondPasses = new ArrayList<>( fkSecondPassList.size() );
			for ( var fkSecondPass : fkSecondPassList ) {
				if ( fkSecondPass.isInPrimaryKey() ) {
					final String referencedEntityName = fkSecondPass.getReferencedEntityName();
					final var classMapping = getEntityBinding( referencedEntityName );
					if ( classMapping == null ) {
						throw new HibernateException( "Primary key referenced an unknown entity: "
													+ referencedEntityName );
					}
					final String dependentTable = classMapping.getTable().getQualifiedTableName().render();
					if ( !isADependencyOf.containsKey( dependentTable ) ) {
						isADependencyOf.put( dependentTable, new HashSet<>() );
					}
					isADependencyOf.get( dependentTable ).add( fkSecondPass );
				}
				else {
					endOfQueueFkSecondPasses.add( fkSecondPass );
				}
			}

			// using the isADependencyOf map we order the FkSecondPass recursively instances into the right order for processing
			final List<FkSecondPass> orderedFkSecondPasses = new ArrayList<>( fkSecondPassList.size() );
			for ( String tableName : isADependencyOf.keySet() ) {
				buildRecursiveOrderedFkSecondPasses( orderedFkSecondPasses, isADependencyOf, tableName, tableName );
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. Make sure the entity referenced as the primary key join target is included in the persistence unit mappings.
2. Check @PrimaryKeyJoinColumn/@MapsId references for correct entity names.
3. Verify the referenced entity class is scanned (correct package in persistence.xml or addAnnotatedClass call).

When it happens

Trigger: A mapping references an entity or collection role that is not known at that point.

Common situations: hbm.xml <key> property-refs or jakarta.persistence cache overrides naming entities/roles that are unmapped or not root entities.

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