What causes "Collection [%s] references an unmapped entity [%s]" in hibernate/hibernate-orm?

Fix the class/entity-name reference on the collection element

hibernate/hibernate-orm · error · MappingException

Collection [%s] references an unmapped entity [%s]

Error message

Collection [%s] references an unmapped entity [%s]

What it means

Binding a plural attribute resolves the referenced entity class of its element (<one-to-many>, <many-to-many>, <map-key-many-to-many>, etc.) through the metadata collector. If getEntityBinding(referencedEntityName) returns null - the target class is unmapped, the name is wrong, or its mapping was never added - the collection binding aborts with the collection's attribute role and the missing entity name in the message.

Source

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

		}

		private static void handleFetchCharacteristics(
				PluralAttributeElementSourceManyToMany elementSource, ManyToOne elementBinding) {
			final var characteristics = elementSource.getFetchCharacteristics();
			elementBinding.setLazy( characteristics.getFetchTiming() != FetchTiming.IMMEDIATE );
			elementBinding.setFetchStyle(
					characteristics.getFetchStyle() == FetchStyle.SELECT
							? FetchStyle.SELECT
							: FetchStyle.JOIN
			);
		}

		private PersistentClass getReferencedEntityBinding(String referencedEntityName) {
			final var entityBinding =
					mappingDocument.getMetadataCollector()
							.getEntityBinding( referencedEntityName );
			if ( entityBinding == null ) {
				throw new MappingException(
						"Collection [%s] references an unmapped entity [%s]"
								.formatted( getPluralAttributeSource().getAttributeRole().getFullPath(),
										referencedEntityName ),
						mappingDocument.getOrigin()
				);
			}
			return entityBinding;
		}
	}

	private class PluralAttributeListSecondPass extends AbstractPluralAttributeSecondPass {
		public PluralAttributeListSecondPass(
				MappingDocument sourceDocument,
				IndexedPluralAttributeSource attributeSource,
				org.hibernate.mapping.List collectionBinding) {
			super( sourceDocument, attributeSource, collectionBinding );
		}

View on GitHub (pinned to fad1729dce)

Solutions

Fix the class/entity-name reference on the collection element
Add the missing target entity mapping (hbm.xml file or annotated class) to the metadata sources
If the target declares an entity-name, reference that exact name everywhere

Example fix

// before
<set name='orders' inverse='true'>
    <key column='customer_id'/>
    <one-to-many class='com.acme.OrderModel'/>
</set>

// after
<set name='orders' inverse='true'>
    <key column='customer_id'/>
    <one-to-many class='com.acme.Order'/>
</set>

Defensive patterns

Strategy: validation

Validate before calling

// before building the factory, assert each collection element target is mapped
Metadata metadata = metadataSources.buildMetadata();
Set<String> names = metadata.getEntityBindings().stream().map(PersistentClass::getEntityName).collect(Collectors.toSet());
if (!names.contains(targetEntityNameOfCollectionElement)) {
    throw new IllegalStateException("collection targets unmapped entity: " + targetEntityNameOfCollectionElement);
}

Type guard

boolean isMappedEntity(Metadata metadata, String name) {
    return metadata.getEntityBinding(name) != null;
}

Try / catch

catch (MappingException e) at bootstrap; the message names the collection role and missing entity. Fix the class/entity-name reference or add the missing mapping, then rebuild.

Prevention

Reference target entities by the exact entity-name they declare
Register every mapping file and annotated class in one place (a shared MetadataSources factory)
Run a SessionFactory startup test in CI to catch dangling references

When it happens

Trigger: <one-to-many class='com.acme.Missing'/> or <many-to-many class='WrongName'/> where the named entity is not among the mapped classes; <map-key-many-to-many> referencing an unmapped class; using an FQCN where the target declared entity-name=.

Common situations: Refactoring or renaming entity classes without updating collection mappings; forgetting to add the target entity's mapping file or annotated class to the Configuration; entity-name vs class-name confusion.

Related errors

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