hibernate/hibernate-orm · error · MappingException

property-ref [" + propertyPath + "] not found on entity [" +

Error message

property-ref [" + propertyPath + "] not found on entity [" + getEntityName() + "]

What it means

A mapping references a property of an entity by name (property-ref) and that property does not exist among the entity's referenceable properties. PersistentClass.getReferencedProperty() delegates to getRecursiveProperty over getReferenceableProperties() and rethrows with this message when the lookup fails. The name typically comes from a many-to-one/one-to-one property-ref attribute or a collection key property-ref.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java:546

	/**
	 * Given a property path, locate the appropriate referenceable property reference.
	 * <p>
	 * A referenceable property is a property  which can be a target of a foreign-key
	 * mapping (e.g. {@code @ManyToOne}, {@code @OneToOne}).
	 *
	 * @param propertyPath The property path to resolve into a property reference.
	 *
	 * @return The property reference (never null).
	 *
	 * @throws MappingException If the property could not be found.
	 */
	public Property getReferencedProperty(String propertyPath) throws MappingException {
		try {
			return getRecursiveProperty( propertyPath, getReferenceableProperties() );
		}
		catch ( MappingException e ) {
			throw new MappingException(
					"property-ref [" + propertyPath + "] not found on entity [" + getEntityName() + "]", e
			);
		}
	}

	public Property getRecursiveProperty(String propertyPath) throws MappingException {
		try {
			return getRecursiveProperty( propertyPath, getPropertyClosure() );
		}
		catch ( MappingException e ) {
			throw new MappingException(
					"property [" + propertyPath + "] not found on entity [" + getEntityName() + "]", e
			);
		}
	}

	private Property getRecursiveProperty(String propertyPath, List<Property> properties) throws MappingException {
		Property property = null;

View on GitHub (pinned to fad1729dce)

Solutions

Fix the property-ref value to match an existing property name on the referenced entity
Verify the referenced class is the one that actually declares the property (check superclasses and subclasses)
For dotted paths, make sure every intermediate segment is an embeddable component
Prefer plain join-column mappings with a unique constraint instead of property-ref where possible

Example fix

// before
<many-to-one name="user" class="com.acme.User" property-ref="userNamee"/>

// after
<many-to-one name="user" class="com.acme.User" property-ref="userName"/>

Defensive patterns

Strategy: validation

Validate before calling

boolean resolvable = targetPc.getReferenceableProperties().stream()
        .anyMatch(p -> p.getName().equals(propertyRefName));
if (!resolvable) {
    // fix the property-ref value before binding the association
}

Prevention

Avoid property-ref: map the foreign key by column and add a unique constraint instead
When renaming fields, grep all mappings for property-ref usages of the old name
Keep a test that boots the full mapping so bad references fail at build time

When it happens

Trigger: A many-to-one or one-to-one pointing at a target entity with property-ref naming a nonexistent property (typo, renamed field); property-ref configured against the wrong entity class; referencing a property declared on a subclass while the reference targets the root; a dotted path whose intermediate segment is not an embeddable.

Common situations: Renaming a Java field without updating XML property-ref attributes; switching the referenced entity class; porting old mappings whose target used to have the property.

Related errors

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