hibernate/hibernate-orm · error · MappingException

property-ref [%s] referenced an unmapped entity [%s]

Error message

property-ref [%s] referenced an unmapped entity [%s]

What it means

property-ref (a legacy feature joining to a named non-PK property of the target, via <many-to-one property-ref=...>, <key property-ref=...>, or one-to-one property-ref) is resolved in a delayed second pass. If metadataCollector.getEntityBinding(referencedEntityName) returns null at that point, the referenced entity was never mapped and the second pass throws with the origin recorded where the property-ref was declared.

Source

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

				Origin propertyRefOrigin) {
			this.referencedEntityName = referencedEntityName;
			this.referencedPropertyName = referencedPropertyName;
			this.isUnique = isUnique;
			this.sourceElementSynopsis = sourceElementSynopsis;
			this.propertyRefOrigin = propertyRefOrigin;
		}

		public void process(InFlightMetadataCollector metadataCollector) {
			BOOT_LOGGER.tracef(
					"Performing delayed property-ref handling [%s, %s, %s]",
					referencedEntityName,
					referencedPropertyName,
					sourceElementSynopsis
			);

			final var entityBinding = metadataCollector.getEntityBinding( referencedEntityName );
			if ( entityBinding == null ) {
				throw new MappingException(
						"property-ref [%s] referenced an unmapped entity [%s]"
								.formatted( sourceElementSynopsis, referencedEntityName ),
						propertyRefOrigin
				);
			}

			final var propertyBinding = entityBinding.getReferencedProperty( referencedPropertyName );
			if ( propertyBinding == null ) {
				throw new MappingException(
						"property-ref [%s] referenced an unknown entity property [%s.%s]"
								.formatted( sourceElementSynopsis, referencedEntityName, referencedPropertyName ),
						propertyRefOrigin
				);
			}

			if ( isUnique ) {
				( (SimpleValue) propertyBinding.getValue() ).setAlternateUniqueKey( true );
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. Correct the referenced entity name to the actually mapped one (respect entity-name vs FQCN)
2. Add the missing target entity mapping to the metadata sources
3. Prefer joining by the target's primary key (drop property-ref) if the schema allows, since property-ref is a legacy construct

Example fix

// before
<many-to-one name='user' class='com.acme.Usr' property-ref='ssn' column='user_ssn'/>

// after
<many-to-one name='user' class='com.acme.User' property-ref='ssn' column='user_ssn'/>

// gather all mapped entity names across sources, then verify each property-ref target exists
Metadata metadata = metadataSources.buildMetadata(); // or scan all <class> names
Set<String> entityNames = metadata.getEntityBindings().stream().map(PersistentClass::getEntityName).collect(Collectors.toSet());
if (!entityNames.contains(referencedEntityNameFromPropertyRef)) {
    throw new IllegalStateException("property-ref targets unmapped entity: " + referencedEntityNameFromPropertyRef);
}

catch (MappingException e) at bootstrap; the message names the property-ref synopsis and the unmapped entity. Correct the name or add the missing mapping - this is deterministic, never retry.

When it happens

Trigger: property-ref='...' pointing at an entity whose name is misspelled or whose mapping file/class is not part of the SessionFactory's sources; using the class FQCN where the target declares an entity-name=.

Common situations: Legacy mappings relying on non-PK joins where the target class moved or was renamed; mapping files omitted during modularization; refactoring that changed entity names.

Related errors

• property-ref [%s] referenced an unknown entity property [%s.
• entity name referenced by many-to-one required [%s]
• No drop foreign key syntax supported by SQLiteDialect
• No add foreign key syntax supported by SQLiteDialect
• SingleStore does not support foreign keys and referential in

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