hibernate/hibernate-orm · error · MappingException

property-ref to unmapped class: {}

Error message

property-ref to unmapped class: {}

What it means

Error "property-ref to unmapped class: {}" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:1361

		return propertyRefResolver == null ? null : propertyRefResolver.get( entityName + "." + propertyName );
	}

	private static class DelayedPropertyReferenceHandlerAnnotationImpl implements DelayedPropertyReferenceHandler {
		public final String referencedClass;
		public final String propertyName;
		public final boolean unique;

		public DelayedPropertyReferenceHandlerAnnotationImpl(String referencedClass, String propertyName, boolean unique) {
			this.referencedClass = referencedClass;
			this.propertyName = propertyName;
			this.unique = unique;
		}

		@Override
		public void process(InFlightMetadataCollector metadataCollector) {
			final var persistentClass = metadataCollector.getEntityBinding( referencedClass );
			if ( persistentClass == null ) {
				throw new MappingException( "property-ref to unmapped class: " + referencedClass );
			}

			final var property = persistentClass.getReferencedProperty( propertyName );
			if ( unique ) {
				( (SimpleValue) property.getValue() ).setAlternateUniqueKey( true );
			}
		}
	}

	@Override
	public void addPropertyReference(String referencedClass, String propertyName) {
		addDelayedPropertyReferenceHandler(
				new DelayedPropertyReferenceHandlerAnnotationImpl( referencedClass, propertyName, false )
		);
	}

	@Override
	public void addDelayedPropertyReferenceHandler(DelayedPropertyReferenceHandler handler) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Ensure the class referenced by property-ref in the hbm/mapping is actually mapped as an entity.
2. Fix typos in the entity/class name used by the property-ref attribute.
3. Check that the referenced entity's mapping file or annotated class is included in the session factory's mapping resources.

When it happens

Trigger: A property-ref refers to a class that is not a mapped entity.

Common situations: hbm.xml property-ref attributes pointing at a class missing from the mapping metadata, or a typo in the class name.

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