hibernate/hibernate-orm · error · MappingException

Referenced entity '" + referencedEntityName + "' does not ex

Error message

Referenced entity '" + referencedEntityName + "' does not exist

What it means

ManyToOne#createPropertyRefConstraints resolves the target of a property-ref association (an association referencing a non-PK property) and throws when no mapped entity exists under the referenced entity name.

Source

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

	 * Creates a {@linkplain ForeignKey foreign key constraint} in the
	 * case that the foreign key of this association does not reference
	 * the primary key of the referenced table, but instead some other
	 * unique key.
	 * <p>
	 * 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(),

View on GitHub (pinned to fad1729dce)

Solutions

1. Set the association's target to the exact mapped entity name (fully-qualified class name or entity-name).
2. If the entity was renamed, update every property-ref association pointing at it.
3. Re-add the entity to the mapping set if it was removed by mistake.

Example fix

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

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

try {
    sessionFactory = configuration.buildSessionFactory();
} catch (MappingException e) {
    // 'Referenced entity <name> does not exist' - check <name> against
    // mapped entity names in this persistence unit
    throw e;
}

When it happens

Trigger: An hbm <many-to-one property-ref="..." class="WrongName">; an entity was renamed or given an explicit entity-name while property-ref mappings kept the old name; the referenced entity was removed from the persistence unit; @Entity(name=...) changed after mappings referencing it were written.

Common situations: Renaming entities or introducing explicit entity names; cleaning up domain models while hbm files keep stale references.

Related errors

• Referenced entity '" + referencedEntityName + "' has no prop
• An association from the table '" + getTable().getName() + "'
• An association from the table '" + getTable().getName() + "'
• one to many association must specify the referenced entity
• property-ref [" + propertyPath + "] not found on entity [" +

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