{"record":{"id":"cf980b506cc8f4f4","repo":"hibernate/hibernate-orm","slug":"primary-key-referenced-an-unknown-entity","errorCode":null,"errorMessage":"Primary key referenced an unknown entity: {}","messagePattern":"Primary key referenced an unknown entity: (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java","lineNumber":1788,"sourceCode":"\t\t\tsecondPasses.clear();\n\t\t}\n\t}\n\n\tprivate void processFkSecondPassesInOrder() {\n\t\tif ( fkSecondPassList == null || fkSecondPassList.isEmpty() ) {\n\t\t\tprocessSecondPasses( secondaryTableFromAnnotationSecondPassesList );\n\t\t}\n\t\telse {\n\t\t\t// split FkSecondPass instances into primary key and non primary key FKs.\n\t\t\t// While doing so build a map of class names to FkSecondPass instances depending on this class.\n\t\t\tfinal Map<String, Set<FkSecondPass>> isADependencyOf = new HashMap<>();\n\t\t\tfinal List<FkSecondPass> endOfQueueFkSecondPasses = new ArrayList<>( fkSecondPassList.size() );\n\t\t\tfor ( var fkSecondPass : fkSecondPassList ) {\n\t\t\t\tif ( fkSecondPass.isInPrimaryKey() ) {\n\t\t\t\t\tfinal String referencedEntityName = fkSecondPass.getReferencedEntityName();\n\t\t\t\t\tfinal var classMapping = getEntityBinding( referencedEntityName );\n\t\t\t\t\tif ( classMapping == null ) {\n\t\t\t\t\t\tthrow new HibernateException( \"Primary key referenced an unknown entity: \"\n\t\t\t\t\t\t\t\t\t\t\t\t\t+ referencedEntityName );\n\t\t\t\t\t}\n\t\t\t\t\tfinal String dependentTable = classMapping.getTable().getQualifiedTableName().render();\n\t\t\t\t\tif ( !isADependencyOf.containsKey( dependentTable ) ) {\n\t\t\t\t\t\tisADependencyOf.put( dependentTable, new HashSet<>() );\n\t\t\t\t\t}\n\t\t\t\t\tisADependencyOf.get( dependentTable ).add( fkSecondPass );\n\t\t\t\t}\n\t\t\t\telse {\n\t\t\t\t\tendOfQueueFkSecondPasses.add( fkSecondPass );\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// using the isADependencyOf map we order the FkSecondPass recursively instances into the right order for processing\n\t\t\tfinal List<FkSecondPass> orderedFkSecondPasses = new ArrayList<>( fkSecondPassList.size() );\n\t\t\tfor ( String tableName : isADependencyOf.keySet() ) {\n\t\t\t\tbuildRecursiveOrderedFkSecondPasses( orderedFkSecondPasses, isADependencyOf, tableName, tableName );\n\t\t\t}","sourceCodeStart":1770,"sourceCodeEnd":1806,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java#L1770-L1806","documentation":"Error \"Primary key referenced an unknown entity: {}\" thrown in hibernate/hibernate-orm.","triggerScenarios":"A mapping references an entity or collection role that is not known at that point.","commonSituations":"hbm.xml <key> property-refs or jakarta.persistence cache overrides naming entities/roles that are unmapped or not root entities.","solutions":["Make sure the entity referenced as the primary key join target is included in the persistence unit mappings.","Check @PrimaryKeyJoinColumn/@MapsId references for correct entity names.","Verify the referenced entity class is scanned (correct package in persistence.xml or addAnnotatedClass call)."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}