{"record":{"id":"69eea81b91478568","repo":"hibernate/hibernate-orm","slug":"unable-to-locate-entity-table-xref-for-entity-s","errorCode":null,"errorMessage":"Unable to locate entity table xref for entity [%s] super-type [%s]","messagePattern":"Unable to locate entity table xref for entity \\[(.+?)\\] super-type \\[(.+?)\\]","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java","lineNumber":2717,"sourceCode":"\t\t\t\t\tdenormalizedSuperTable\n\t\t\t);\n\t\t}\n\t\ttable.setName( logicalTableName.render() );\n\t\treturn table;\n\t}\n\n\tprivate static EntityTableXref superEntityTableXref(\n\t\t\tMappingDocument mappingDocument,\n\t\t\tEntitySource entitySource,\n\t\t\tPersistentClass entityDescriptor,\n\t\t\tInFlightMetadataCollector metadataCollector) {\n\t\tfinal var superType = entitySource.getSuperType();\n\t\tif ( superType != null ) {\n\t\t\tfinal var supertype = (EntitySource) superType;\n\t\t\tfinal String superEntityName = supertype.getEntityNamingSource().getEntityName();\n\t\t\tfinal var superEntityTableXref = metadataCollector.getEntityTableXref( superEntityName );\n\t\t\tif ( superEntityTableXref == null ) {\n\t\t\t\tthrow new MappingException(\n\t\t\t\t\t\t\"Unable to locate entity table xref for entity [%s] super-type [%s]\"\n\t\t\t\t\t\t\t\t.formatted( entityDescriptor.getEntityName(), superEntityName ),\n\t\t\t\t\t\tmappingDocument.getOrigin()\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn superEntityTableXref;\n\t\t}\n\t\telse {\n\t\t\treturn null;\n\t\t}\n\t}\n\n\tprivate Identifier determineCatalogName(TableSpecificationSource tableSpecSource) {\n\t\tfinal String explicitCatalogName = tableSpecSource.getExplicitCatalogName();\n\t\treturn isNotEmpty( explicitCatalogName )\n\t\t\t\t? database.toIdentifier( explicitCatalogName )\n\t\t\t\t: null;\n\t}","sourceCodeStart":2699,"sourceCodeEnd":2735,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java#L2699-L2735","documentation":"When binding an entity with a super-type (<subclass>, <joined-subclass>, <union-subclass>), Hibernate looks up the EntityTableXref registered when the super entity was bound, in order to link primary/foreign keys across the hierarchy. If no xref exists for the super entity name, the inheritance chain is broken - usually because extends= names no bound entity or the superclass mapping was never processed.","triggerScenarios":"<subclass extends='WrongOrMisspelledName'>; only part of an inheritance tree included in the MetadataSources; duplicate entity names shadowing the super entity; extends= using the FQCN when the super declares entity-name= (or vice versa).","commonSituations":"Typos or stale package-qualified names in extends=; splitting inheritance mappings across files and forgetting to add the root class mapping during modularization; refactoring that renamed entity-name declarations.","solutions":["Fix extends= to exactly match the super entity's entity-name (or its FQCN when no entity-name is declared)","Make sure the root class mapping (hbm.xml or annotated class) is added to the same Configuration/MetadataSources","Check for duplicate entity definitions mapping the same entity name twice, which can break the binding chain"],"exampleFix":"// before\n<subclass name='AdminUser' extends='com.acme.Usr' discriminator-value='A'>\n\n// after\n<subclass name='AdminUser' extends='com.acme.User' discriminator-value='A'>","handlingStrategy":"validation","validationCode":"// collect every extends= target and verify a mapping declares that name\nSet<String> declared = new HashSet<>();\nNodeList classes = doc.getElementsByTagName(\"class\");\nfor (int i = 0; i < classes.getLength(); i++) {\n    Element c = (Element) classes.item(i);\n    declared.add(c.getAttributeNode(\"entity-name\") != null ? c.getAttribute(\"entity-name\") : c.getAttribute(\"class\"));\n}\nString[] subs = {\"subclass\", \"joined-subclass\", \"union-subclass\"};\nfor (String tag : subs) {\n    NodeList nodes = doc.getElementsByTagName(tag);\n    for (int i = 0; i < nodes.getLength(); i++) {\n        String ext = ((Element) nodes.item(i)).getAttribute(\"extends\");\n        if (!declared.contains(ext)) {\n            throw new IllegalStateException(\"extends target not mapped: \" + ext);\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"catch (MappingException e) at bootstrap; the message gives the entity and the super-type name it could not link. Fix extends= or add the missing super mapping to the same MetadataSources, then rebuild.","preventionTips":["Keep an inheritance hierarchy in one mapping file or ensure all files are loaded together","Use the exact entity-name declared by the root class in extends=","Add a startup smoke test that builds the SessionFactory before deploying"],"tags":["hibernate","hbm-mapping","inheritance","subclass","table-xref"],"backgroundTag":"orm-inheritance-mapping-error","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}