hibernate/hibernate-orm · error · MappingException

An association from the table '" + getTable().getName() + "'

Error message

An association from the table '" + getTable().getName() + "' does not specify the referenced entity

What it means

ForeignKey#resolveReferencedClass throws when a mapped association's foreign key carries no referenced entity name at all. Hibernate needs the target entity to resolve the FK, so a key or association that never had its entity set is an incomplete mapping - typically a truncated hbm fragment.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/ForeignKey.java:192

	}

	public String toString() {
		if ( !isReferenceToPrimaryKey() ) {
			return getClass().getSimpleName()
					+ '(' + getTable().getName() + getColumns()
					+ " ref-columns:" + '(' + getReferencedColumns() + ") as " + getName() + ")";
		}
		else {
			return super.toString();
		}

	}

	@Internal
	public PersistentClass resolveReferencedClass(Metadata metadata) {
		final String referencedEntityName = getReferencedEntityName();
		if ( referencedEntityName == null ) {
			throw new MappingException( "An association from the table '" + getTable().getName() +
					"' does not specify the referenced entity" );
		}

		final var referencedEntity = metadata.getEntityBinding( referencedEntityName );
		if ( referencedEntity == null ) {
			throw new MappingException( "An association from the table '" + getTable().getName() +
					"' refers to an unmapped class '" + referencedEntityName + "'" );
		}

		return referencedEntity;
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

Add the missing target: <one-to-many class="com.acme.Item"/> or set the referenced entity name programmatically.
Validate that every hbm file loads and every association names its target entity.
Prefer annotation or programmatic mappings where the target entity is checked at compile time.

Example fix

<!-- before -->
<set name="items" table="item">
    <key column="order_id"/>
    <one-to-many/>
</set>

<!-- after -->
<set name="items" table="item">
    <key column="order_id"/>
    <one-to-many class="com.acme.Item"/>
</set>

Defensive patterns

Strategy: try-catch

Try / catch

try {
    sessionFactory = configuration.buildSessionFactory();
} catch (MappingException e) {
    // message includes the owning table - search mappings for associations
    // on that table that lack a class / entity-name
    throw e;
}

Prevention

Never leave <one-to-many> or <many-to-many> elements without class or entity-name in hbm files.
Validate hbm files against the Hibernate mapping XSD so structurally incomplete elements are rejected early.
Add a startup or CI check that parses every hbm file and builds Metadata.

When it happens

Trigger: An hbm <one-to-many> element without its class attribute inside a bag or set; a programmatic mapping where setReferencedEntityName was never called; hand-edited hbm where the class attribute was deleted; mapping fragments loaded from templated files with placeholders unfilled.

Common situations: Hand-written or templated hbm.xml files; copy-paste mapping templates; XML processed by build tooling that strips attributes; migrations between annotation and hbm styles.

Related errors

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