{"record":{"id":"8b03a1e85d285a4c","repo":"hibernate/hibernate-orm","slug":"an-association-from-the-table-gettable-getn-8b03a1","errorCode":null,"errorMessage":"An association from the table '\" + getTable().getName() + \"' refers to an unmapped class '\" + referencedEntityName + \"'","messagePattern":"An association from the table '\" \\+ getTable\\(\\)\\.getName\\(\\) \\+ \"' refers to an unmapped class '\" \\+ referencedEntityName \\+ \"'","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java","lineNumber":198,"sourceCode":"\t\t\t\t\t+ \" ref-columns:\" + '(' + getReferencedColumns() + \") as \" + getName() + \")\";\n\t\t}\n\t\telse {\n\t\t\treturn super.toString();\n\t\t}\n\n\t}\n\n\t@Internal\n\tpublic PersistentClass resolveReferencedClass(Metadata metadata) {\n\t\tfinal String referencedEntityName = getReferencedEntityName();\n\t\tif ( referencedEntityName == null ) {\n\t\t\tthrow new MappingException( \"An association from the table '\" + getTable().getName() +\n\t\t\t\t\t\"' does not specify the referenced entity\" );\n\t\t}\n\n\t\tfinal var referencedEntity = metadata.getEntityBinding( referencedEntityName );\n\t\tif ( referencedEntity == null ) {\n\t\t\tthrow new MappingException( \"An association from the table '\" + getTable().getName() +\n\t\t\t\t\t\"' refers to an unmapped class '\" + referencedEntityName + \"'\" );\n\t\t}\n\n\t\treturn referencedEntity;\n\t}\n}\n","sourceCodeStart":180,"sourceCodeEnd":205,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java#L180-L205","documentation":"ForeignKey#resolveReferencedClass looks up the referenced entity by name in the built metadata and throws when no entity binding exists under that exact name. The FK therefore points at a class that is not part of the persistence unit's mapping set.","triggerScenarios":"Referencing an @Entity(name=\"X\") custom name with the plain class name or vice versa; the target class lacks @Entity or is missing from persistence.xml / the annotated-classes list; an entity-name string in hbm has a typo; the entity jar is not included in the persistence unit.","commonSituations":"Introducing explicit @Entity names during cleanup; splitting the domain into modules and forgetting to register some entities; dynamic hbm mappings assembled from files; differing entity-name conventions across teams.","solutions":["Make the referenced name exactly match the mapped entity: the @Entity(name=...) value, the hbm entity-name attribute, or the fully-qualified class name when no explicit name is set.","Ensure the target class has @Entity and is included via component scanning, persistence.xml <class>, or MetadataSources.","If the name is correct, verify the entity's artifact is actually part of the persistence unit."],"exampleFix":"// before - entity declared with an explicit name\n@Entity(name = \"ItemMaster\")\npublic class Item { ... }\n// mapping references \"Item\"\n\n// after - align the reference (or drop the explicit name)\n@Entity\npublic class Item { ... }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (MappingException e) {\n    // 'refers to an unmapped class <name>' - compare <name> against the\n    // scanned entity set (@Entity names / entity-name attributes)\n    throw e;\n}","preventionTips":["Avoid @Entity(name=...) unless required; default names keep references stable.","Assert in a test that every entity name referenced by mappings exists in the scanned entity set.","Keep persistence.xml or the annotated-classes list in sync when moving entities between modules."],"tags":["hibernate","orm","mapping","entity","persistence-unit","referenced-entity"],"backgroundTag":"entity-not-mapped","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}