What causes "Unable to locate entity table xref for entity [%s] super-type [%s]" in hibernate/hibernate-orm?

Fix extends= to exactly match the super entity's entity-name (or its FQCN when no entity-name is declared)

hibernate/hibernate-orm · error · MappingException

Unable to locate entity table xref for entity [%s] super-typ

Error message

Unable to locate entity table xref for entity [%s] super-type [%s]

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/source/internal/hbm/ModelBinder.java:2717

					denormalizedSuperTable
			);
		}
		table.setName( logicalTableName.render() );
		return table;
	}

	private static EntityTableXref superEntityTableXref(
			MappingDocument mappingDocument,
			EntitySource entitySource,
			PersistentClass entityDescriptor,
			InFlightMetadataCollector metadataCollector) {
		final var superType = entitySource.getSuperType();
		if ( superType != null ) {
			final var supertype = (EntitySource) superType;
			final String superEntityName = supertype.getEntityNamingSource().getEntityName();
			final var superEntityTableXref = metadataCollector.getEntityTableXref( superEntityName );
			if ( superEntityTableXref == null ) {
				throw new MappingException(
						"Unable to locate entity table xref for entity [%s] super-type [%s]"
								.formatted( entityDescriptor.getEntityName(), superEntityName ),
						mappingDocument.getOrigin()
				);
			}
			return superEntityTableXref;
		}
		else {
			return null;
		}
	}

	private Identifier determineCatalogName(TableSpecificationSource tableSpecSource) {
		final String explicitCatalogName = tableSpecSource.getExplicitCatalogName();
		return isNotEmpty( explicitCatalogName )
				? database.toIdentifier( explicitCatalogName )
				: null;
	}

View on GitHub (pinned to fad1729dce)

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

Example fix

// before
<subclass name='AdminUser' extends='com.acme.Usr' discriminator-value='A'>

// after
<subclass name='AdminUser' extends='com.acme.User' discriminator-value='A'>

Defensive patterns

Strategy: validation

Validate before calling

// collect every extends= target and verify a mapping declares that name
Set<String> declared = new HashSet<>();
NodeList classes = doc.getElementsByTagName("class");
for (int i = 0; i < classes.getLength(); i++) {
    Element c = (Element) classes.item(i);
    declared.add(c.getAttributeNode("entity-name") != null ? c.getAttribute("entity-name") : c.getAttribute("class"));
}
String[] subs = {"subclass", "joined-subclass", "union-subclass"};
for (String tag : subs) {
    NodeList nodes = doc.getElementsByTagName(tag);
    for (int i = 0; i < nodes.getLength(); i++) {
        String ext = ((Element) nodes.item(i)).getAttribute("extends");
        if (!declared.contains(ext)) {
            throw new IllegalStateException("extends target not mapped: " + ext);
        }
    }
}

Try / catch

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.

Prevention

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

When it happens

Trigger: <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).

Common situations: 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.

Related errors

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