hibernate/hibernate-orm · error · MappingException

Association '${path}' targets the type '${type}' which does

Error message

Association '${path}' targets the type '${type}' which does not belong to the same persistence unit

What it means

During the second pass of @OneToOne binding, Hibernate looks the association's target entity name up in the mapped-class registry of the persistence unit. The lookup returned null for a class that is annotated as an entity, so it concludes the type was never included in this persistence unit and fails with MappingException at bootstrap.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/model/internal/OneToOneSecondPass.java:91

		if ( mappedBy == null ) {
			bindOwned( persistentClasses, oneToOne, inferredData.getPropertyName() );
		}
		else {
			bindUnowned( persistentClasses, oneToOne );
		}
		binder.callAttributeBindersInSecondPass( property );
		oneToOne.sortProperties();
	}

	private void bindUnowned(Map<String, PersistentClass> persistentClasses, OneToOne oneToOne) {
		oneToOne.setMappedByProperty( mappedBy );
		final String targetEntityName = oneToOne.getReferencedEntityName();
		final var targetEntity = persistentClasses.get( targetEntityName );
		if ( targetEntity == null ) {
			final String problem = annotatedEntity
					? " which does not belong to the same persistence unit"
					: " which is not an '@Entity' type";
			throw new MappingException( "Association '" + getPath( propertyHolder, inferredData )
					+ "' targets the type '" + targetEntityName + "'" + problem );
		}
		final var targetProperty = targetProperty( oneToOne, targetEntity );
		final var targetPropertyValue = targetProperty.getValue();
		if ( targetPropertyValue instanceof ManyToOne ) {
			bindTargetManyToOne( persistentClasses, oneToOne, targetEntity, targetProperty );
		}
		else if ( !(targetPropertyValue instanceof OneToOne) ) {
			throw new AnnotationException( "Association '" + getPath( propertyHolder, inferredData )
					+ "' is 'mappedBy' a property named '" + mappedBy
					+ "' of the target entity type '" + targetEntityName
					+ "' which is not a '@OneToOne' or '@ManyToOne' association" );
		}
		checkMappedByType(
				mappedBy,
				targetPropertyValue,
				oneToOne.getPropertyName(),
				propertyHolder,

View on GitHub (pinned to fad1729dce)

Solutions

Add the target class to the persistence unit: persistence.xml <class>com.example.Other</class> or hibernate.cfg.xml <mapping class="com.example.Other"/>.
In Spring Boot, extend @EntityScan basePackages (or the auto-configuration's scan) so the package containing the target entity is included.
If multiple persistence units exist, make sure both sides of the association are in the same unit.
If the target was never meant to be an entity, remove targetEntity / change the field type, since a @OneToOne must target a managed entity.

Example fix

// before: Other is @Entity but not in the persistence unit
@OneToOne
private Other other;

// persistence.xml
<persistence-unit name="pu">
  <class>com.example.MainEntity</class>
  <!-- Other missing -->
</persistence-unit>

// after
<persistence-unit name="pu">
  <class>com.example.MainEntity</class>
  <class>com.example.Other</class>
</persistence-unit>

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify every association target resolves to a class in the mapped set
Set<Class<?>> mapped = Set.copyOf(annotatedClasses);
for (Class<?> entity : mapped) {
    for (Field f : entity.getDeclaredFields()) {
        Class<?> target = f.getType();
        OneToOne o2o = f.getAnnotation(OneToOne.class);
        if (o2o != null && o2o.targetEntity() != void.class) target = o2o.targetEntity();
        if (o2o != null && !target.isAnnotationPresent(Entity.class)) {
            throw new IllegalStateException(f + " targets non-entity " + target);
        }
    }
}

Type guard

static boolean isMappedEntity(Class<?> candidate, Set<Class<?>> mappedUnits) {
    return candidate.isAnnotationPresent(Entity.class) && mappedUnits.contains(candidate);
}

Try / catch

try {
    Metadata md = new MetadataSources(registry).addAnnotatedClasses(annotated).buildMetadata();
} catch (MappingException e) {
    // 'does not belong to the same persistence unit' => fix classlist; surface a class-list diff
    throw new IllegalStateException("Association target missing from persistence unit: " + e.getMessage(), e);
}

Prevention

Keep @EntityScan basePackages broad enough to cover association targets in modular projects
List every entity in persistence.xml when not using scanning
Run a CI test that boots the full persistence unit

When it happens

Trigger: @OneToOne(targetEntity = Other.class) or @OneToOne on a field of type Other, where Other is a @Entity class that is not part of the metadata being built: not listed in persistence.xml <class>, outside the @EntityScan base packages in Spring Boot, missing from hibernate.cfg.xml <mapping class=...>, or discovered by a different EntityManagerFactory.

Common situations: Spring Boot apps where the associated entity lives in a module/package outside the default scan root; classic persistence.xml setups that require explicit <class> entries and missed one; multiple persistence units where the entity is registered in unit A but referenced from unit B; moving entities between modules during refactoring; test bootstrap that maps a subset of classes.

Related errors

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