{"record":{"id":"2db88a74f033f1f2","repo":"hibernate/hibernate-orm","slug":"collection-s-references-an-unmapped-entity-s","errorCode":null,"errorMessage":"Collection [%s] references an unmapped entity [%s]","messagePattern":"Collection \\[(.+?)\\] references an unmapped entity \\[(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java","lineNumber":3333,"sourceCode":"\t\t}\n\n\t\tprivate static void handleFetchCharacteristics(\n\t\t\t\tPluralAttributeElementSourceManyToMany elementSource, ManyToOne elementBinding) {\n\t\t\tfinal var characteristics = elementSource.getFetchCharacteristics();\n\t\t\telementBinding.setLazy( characteristics.getFetchTiming() != FetchTiming.IMMEDIATE );\n\t\t\telementBinding.setFetchStyle(\n\t\t\t\t\tcharacteristics.getFetchStyle() == FetchStyle.SELECT\n\t\t\t\t\t\t\t? FetchStyle.SELECT\n\t\t\t\t\t\t\t: FetchStyle.JOIN\n\t\t\t);\n\t\t}\n\n\t\tprivate PersistentClass getReferencedEntityBinding(String referencedEntityName) {\n\t\t\tfinal var entityBinding =\n\t\t\t\t\tmappingDocument.getMetadataCollector()\n\t\t\t\t\t\t\t.getEntityBinding( referencedEntityName );\n\t\t\tif ( entityBinding == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"Collection [%s] references an unmapped entity [%s]\"\n\t\t\t\t\t\t\t\t.formatted( getPluralAttributeSource().getAttributeRole().getFullPath(),\n\t\t\t\t\t\t\t\t\t\treferencedEntityName ),\n\t\t\t\t\t\tmappingDocument.getOrigin()\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn entityBinding;\n\t\t}\n\t}\n\n\tprivate class PluralAttributeListSecondPass extends AbstractPluralAttributeSecondPass {\n\t\tpublic PluralAttributeListSecondPass(\n\t\t\t\tMappingDocument sourceDocument,\n\t\t\t\tIndexedPluralAttributeSource attributeSource,\n\t\t\t\torg.hibernate.mapping.List collectionBinding) {\n\t\t\tsuper( sourceDocument, attributeSource, collectionBinding );\n\t\t}\n","sourceCodeStart":3315,"sourceCodeEnd":3351,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java#L3315-L3351","documentation":"Binding a plural attribute resolves the referenced entity class of its element (<one-to-many>, <many-to-many>, <map-key-many-to-many>, etc.) through the metadata collector. If getEntityBinding(referencedEntityName) returns null - the target class is unmapped, the name is wrong, or its mapping was never added - the collection binding aborts with the collection's attribute role and the missing entity name in the message.","triggerScenarios":"<one-to-many class='com.acme.Missing'/> or <many-to-many class='WrongName'/> where the named entity is not among the mapped classes; <map-key-many-to-many> referencing an unmapped class; using an FQCN where the target declared entity-name=.","commonSituations":"Refactoring or renaming entity classes without updating collection mappings; forgetting to add the target entity's mapping file or annotated class to the Configuration; entity-name vs class-name confusion.","solutions":["Fix the class/entity-name reference on the collection element","Add the missing target entity mapping (hbm.xml file or annotated class) to the metadata sources","If the target declares an entity-name, reference that exact name everywhere"],"exampleFix":"// before\n<set name='orders' inverse='true'>\n    <key column='customer_id'/>\n    <one-to-many class='com.acme.OrderModel'/>\n</set>\n\n// after\n<set name='orders' inverse='true'>\n    <key column='customer_id'/>\n    <one-to-many class='com.acme.Order'/>\n</set>","handlingStrategy":"validation","validationCode":"// before building the factory, assert each collection element target is mapped\nMetadata metadata = metadataSources.buildMetadata();\nSet<String> names = metadata.getEntityBindings().stream().map(PersistentClass::getEntityName).collect(Collectors.toSet());\nif (!names.contains(targetEntityNameOfCollectionElement)) {\n    throw new IllegalStateException(\"collection targets unmapped entity: \" + targetEntityNameOfCollectionElement);\n}","typeGuard":"boolean isMappedEntity(Metadata metadata, String name) {\n    return metadata.getEntityBinding(name) != null;\n}","tryCatchPattern":"catch (MappingException e) at bootstrap; the message names the collection role and missing entity. Fix the class/entity-name reference or add the missing mapping, then rebuild.","preventionTips":["Reference target entities by the exact entity-name they declare","Register every mapping file and annotated class in one place (a shared MetadataSources factory)","Run a SessionFactory startup test in CI to catch dangling references"],"tags":["hibernate","hbm-mapping","collection","one-to-many","unmapped-entity"],"backgroundTag":"unmapped-entity-reference","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}