What causes "one to many association must specify the referenced entity" in hibernate/hibernate-orm?

Add class="com.acme.Item" (or entity-name="...") to the element.

hibernate/hibernate-orm · error · MappingException

one to many association must specify the referenced entity

Error message

one to many association must specify the referenced entity

What it means

OneToMany#isValid throws when a one-to-many association mapping carries no referenced entity name. The mapping element (hbm <one-to-many> without class, or a programmatic OneToMany never given its target) is incomplete, so Hibernate cannot bind the association.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/OneToMany.java:155

	@Override
	public boolean isSimpleValue() {
		return false;
	}

	@Override
	public boolean isAlternateUniqueKey() {
		return false;
	}

	@Override
	public boolean hasFormula() {
		return false;
	}

	@Override
	public boolean isValid(MappingContext mappingContext) throws MappingException {
		if ( referencedEntityName == null ) {
			throw new MappingException( "one to many association must specify the referenced entity" );
		}
		return true;
	}

	public String getReferencedEntityName() {
		return referencedEntityName;
	}

	/**
	 * Associated entity on the "many" side
	 */
	public void setReferencedEntityName(String referencedEntityName) {
		this.referencedEntityName = referencedEntityName == null ? null : referencedEntityName.intern();
	}

	@Override
	public void setTypeUsingReflection(String className, String propertyName) {
	}

View on GitHub (pinned to fad1729dce)

Solutions

Add class="com.acme.Item" (or entity-name="...") to the <one-to-many> element.
If using the programmatic API, call setReferencedEntityName with the mapped entity name.
Add a metadata-build test so incomplete collection mappings fail in CI instead of at boot.

Example fix

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

<!-- after -->
<set name="items">
    <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) {
    // stack trace shows the owning collection - complete its
    // <one-to-many class="..."> element
    throw e;
}

Prevention

Always fully specify association targets in hbm; validate files against the hbm XSD.
Prefer annotations where the compiler checks the target class reference.
Build Metadata for all mappings in CI so incomplete collections fail early.

When it happens

Trigger: An hbm <one-to-many/> element without the class attribute; a programmatic mapping where setReferencedEntityName was never called; XML templating dropping the class attribute; mappings generated with unfilled placeholders.

Common situations: Hand-written hbm collection mappings; copy-paste omissions; dynamically assembled XML mapping files.

Related errors

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