hibernate/hibernate-orm · error · MappingException

property-ref [%s] referenced an unknown entity property [%s.

Error message

property-ref [%s] referenced an unknown entity property [%s.%s]

What it means

The companion of the unmapped-entity check: the entity referenced by property-ref IS bound, but entityBinding.getReferencedProperty(referencedPropertyName) returned null - the property named by property-ref does not exist on the target entity as a referable (persistent) property. Thrown from the same delayed second pass with the property-ref origin.

Source

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

			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 );
			}
		}
	}

	private abstract class AbstractPluralAttributeSecondPass implements SecondPass {
		private final MappingDocument mappingDocument;
		private final PluralAttributeSource pluralAttributeSource;
		private final Collection collectionBinding;

		protected AbstractPluralAttributeSecondPass(

View on GitHub (pinned to fad1729dce)

Solutions

1. Align property-ref with an existing, ideally unique, persistent property of the target entity
2. If the target property was renamed, update every property-ref that names it
3. Make sure the referenced property is actually mapped (<property> and not transient/calculated)

Example fix

// before
<many-to-one name='user' class='User' property-ref='userName' column='login'/>

// after
<many-to-one name='user' class='User' property-ref='loginName' column='login'/>

// after all classes are mapped, verify each property-ref names a real persistent property
PersistentClass pc = metadata.getEntityBinding(referencedEntityName);
if (pc.getReferencedProperty(referencedPropertyName) == null) {
    throw new IllegalStateException("property-ref names unknown property " + referencedEntityName + "." + referencedPropertyName);
}

catch (MappingException e) at bootstrap; the message gives entity and property. Rename the property-ref value to a mapped (ideally unique) property of that entity.

When it happens

Trigger: property-ref='userName' where the target entity has no such persistent property; the target field was renamed while the referencing mapping kept the old name; referencing a transient/computed field or a path that is not exposed as a referable property.

Common situations: Field renames on the target entity without sweeping property-ref usages; unique-key columns later removed from the mapping; case mismatches in property names.

Related errors

• property-ref [%s] referenced an unmapped entity [%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/c8c180a0c78700e7. Report an issue: GitHub.