hibernate/hibernate-orm · error · MappingException

entity name referenced by many-to-one required [%s]

Error message

entity name referenced by many-to-one required [%s]

What it means

ManyToOneFkSecondPass creates the foreign key for a bound many-to-one and requires the referenced entity name; its constructor guards against null because FK creation has nothing to point at. In practice a null name only slips through unusual programmatic source construction, since normal hbm.xml parsing demands class= or entity-name= on <many-to-one> before this point.

Source

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

				);
			}
		}
	}

	private static class ManyToOneFkSecondPass implements FkSecondPass {
		private final MappingDocument mappingDocument;
		private final ManyToOne manyToOneBinding;

		private final String referencedEntityName;
		private final String referencedEntityAttributeName;

		private ManyToOneFkSecondPass(
				MappingDocument mappingDocument,
				SingularAttributeSourceManyToOne manyToOneSource,
				ManyToOne manyToOneBinding,
				String referencedEntityName) {
			if ( referencedEntityName == null ) {
				throw new MappingException(
						"entity name referenced by many-to-one required [%s]"
								.formatted( manyToOneSource.getAttributeRole().getFullPath() ),
						mappingDocument.getOrigin()
				);
			}
			this.mappingDocument = mappingDocument;
			this.manyToOneBinding = manyToOneBinding;
			this.referencedEntityName = referencedEntityName;
			this.referencedEntityAttributeName = manyToOneSource.getReferencedEntityAttributeName();
		}

		@Override
		public Value getValue() {
			return manyToOneBinding;
		}

		@Override
		public String getReferencedEntityName() {

View on GitHub (pinned to fad1729dce)

Solutions

1. Ensure the <many-to-one> element defines class= or entity-name=
2. If building attribute sources programmatically, never return null from the referenced entity name accessor - validate before registering the source
3. Regenerate or repair the malformed mapping file if a tool produced it

Example fix

// before
<many-to-one name='dept' column='dept_id'/>

// after
<many-to-one name='dept' class='com.acme.Department' column='dept_id'/>

NodeList mto = doc.getElementsByTagName("many-to-one");
for (int i = 0; i < mto.getLength(); i++) {
    Element m = (Element) mto.item(i);
    boolean hasTarget = m.getAttributeNode("class") != null || m.getAttributeNode("entity-name") != null;
    if (!hasTarget) {
        throw new IllegalStateException("<many-to-one '" + m.getAttribute("name") + "'> has no class/entity-name");
    }
}

catch (MappingException e) at bootstrap; add class= or entity-name= to the named many-to-one. If sources are built programmatically, fix the accessor that returned null.

When it happens

Trigger: A hand-implemented SingularAttributeSourceManyToOne (custom metadata source or tooling) whose referenced-entity accessor returns null; a corrupted/hand-mangled hbm.xml where the parser produced no class or entity-name for a many-to-one.

Common situations: Custom Binding or metadata-source tooling building attribute sources programmatically; edge-case mappings generated by external tools.

Related errors

• many-to-one attribute [%s] specified delete-orphan but is no
• property-ref [%s] referenced an unmapped entity [%s]
• property-ref [%s] referenced an unknown entity property [%s.
• Unable to determine foreign key target Type for many-to-one
• No drop foreign key syntax supported by SQLiteDialect

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