hibernate/hibernate-orm · error · MappingException

Referenced entity '" + referencedEntityName + "' has no prop

Error message

Referenced entity '" + referencedEntityName + "' has no property named '" + referencedPropertyName + "'

What it means

ManyToOne#createPropertyRefConstraints throws when the target entity exists but exposes no property under the referenced property name. The association points at a field the target mapping does not declare or does not expose as a persistent property.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/ManyToOne.java:89

	 * We depend here on having a property of the referenced entity
	 * that does hold the referenced unique key. We might have created
	 * a "synthetic" composite property for this purpose.
	 */
	public void createPropertyRefConstraints(Map<String, PersistentClass> persistentClasses) {
		if ( referencedPropertyName != null ) {
			// Ensure properties are sorted before we create a foreign key
			sortProperties();

			final String referencedEntityName = getReferencedEntityName();
			final String referencedPropertyName = getReferencedPropertyName();
			final var referencedClass = persistentClasses.get( referencedEntityName );
			if ( referencedClass == null ) {
				throw new MappingException( "Referenced entity '" + referencedEntityName + "' does not exist" );

			}
			final var property = referencedClass.getReferencedProperty( referencedPropertyName );
			if ( property==null ) {
				throw new MappingException( "Referenced entity '" + referencedEntityName
						+ "' has no property named '" + referencedPropertyName + "'" );
			}
			else {
				// Make sure synthetic properties are sorted
				if ( property.getValue() instanceof Component component ) {
					component.sortProperties();
				}
				// todo : if "none" another option is to create the ForeignKey object still	but to set its #disableCreation flag
				if ( isConstrained() && !hasAuxiliaryColumnInPrimaryKey( referencedClass ) ) {
					final var foreignKey = getTable().createForeignKey(
							getForeignKeyName(),
							getConstraintColumns(),
							getType().getAssociatedEntityName(),
							getForeignKeyDefinition(),
							getForeignKeyOptions(),
							new ArrayList<>( property.getColumns() )
					);
					foreignKey.setReferencedTable( property.getValue().getTable() );

View on GitHub (pinned to fad1729dce)

Solutions

Use the exact persistent property name - check the target entity's mapping, not just the Java field.
If the property was renamed, update the property-ref value everywhere it appears.
Ensure the referenced property is persistent (not @Transient) and unique - property-refs must target a unique column.

Example fix

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

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

Defensive patterns

Strategy: try-catch

Try / catch

try {
    sessionFactory = configuration.buildSessionFactory();
} catch (MappingException e) {
    // message pairs entity + property name - verify the property exists
    // in the target mapping and is unique
    throw e;
}

Prevention

Prefer primary-key references instead of property-ref when possible.
When renaming properties, search all mappings for property-ref attributes.
Keep a unique constraint on every property-ref target so the implicit FK stays valid.

When it happens

Trigger: property-ref="ssoToken" while the entity's persistent property is named sso; the referenced property was renamed or made @Transient; the property lives on a subclass or superclass not visible through the referenced binding; access-type changes hiding the field.

Common situations: Refactors renaming target properties; copy-paste of property-ref values; switching field/getter access so a property no longer appears in the mapping.

Related errors

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