hibernate/hibernate-orm · error · AnnotationException

Association '${path}' is 'mappedBy' a property named '${mapp

Error message

Association '${path}' is 'mappedBy' a property named '${mappedBy}' which does not exist in the target entity type '${type}'

What it means

The mappedBy attribute of a @OneToOne names a property on the target entity, and Hibernate could not find any property with that name (findPropertyByName returned null or threw). Without the inverse property the association cannot be wired, so AnnotationException is thrown at bootstrap.

Source

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

		manyToOne.setLazy( oneToOne.isLazy() );
		manyToOne.setReferencedEntityName( oneToOne.getReferencedEntityName() );
		manyToOne.setReferencedPropertyName( mappedBy );
		manyToOne.setUnwrapProxy( oneToOne.isUnwrapProxy() );
		manyToOne.markAsLogicalOneToOne();
		return manyToOne;
	}

	private Property targetProperty(OneToOne oneToOne, PersistentClass targetEntity) {
		try {
			final var targetProperty = findPropertyByName( targetEntity, mappedBy );
			if ( targetProperty != null ) {
				return targetProperty;
			}
		}
		catch (MappingException e) {
			// swallow it
		}
		throw new AnnotationException( "Association '" + getPath( propertyHolder, inferredData )
				+ "' is 'mappedBy' a property named '" + mappedBy
				+ "' which does not exist in the target entity type '" + oneToOne.getReferencedEntityName() + "'" );
	}

	private void bindOwned(
			Map<String, PersistentClass> persistentClasses,
			OneToOne oneToOne,
			String propertyName) {
		final ToOneFkSecondPass secondPass = new ToOneFkSecondPass(
				oneToOne,
				joinColumns,
				true,
				annotatedEntity,
				propertyHolder.getPersistentClass(),
				qualify( propertyHolder.getPath(), propertyName ),
				buildingContext
		);
		secondPass.doSecondPass(persistentClasses);

View on GitHub (pinned to fad1729dce)

Solutions

Open the target entity and copy the exact Java property name of the owning side into mappedBy.
If the owning field was renamed, update every mappedBy that references the old name.
Verify targetEntity (explicit or inferred from the field type) really is the class that holds the owning property.

Example fix

// before
public class User {
    @OneToOne(mappedBy = "usr")
    private Profile profile;
}
public class Profile {
    @OneToOne
    @JoinColumn(name = "user_id")
    private User user;
}

// after
@OneToOne(mappedBy = "user")
private Profile profile;

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast on mappedBy typos: the name must exist on the target entity
for (Class<?> entity : annotatedClasses) {
    for (Field f : entity.getDeclaredFields()) {
        OneToOne o2o = f.getAnnotation(OneToOne.class);
        if (o2o == null || o2o.mappedBy().isEmpty()) continue;
        try {
            f.getType().getDeclaredField(o2o.mappedBy());
        } catch (NoSuchFieldException e) {
            throw new IllegalStateException("mappedBy '" + o2o.mappedBy() + "' does not exist on " + f.getType().getSimpleName());
        }
    }
}

Type guard

static boolean mappedByExists(Class<?> target, String mappedBy) {
    try { target.getDeclaredField(mappedBy); return true; }
    catch (NoSuchFieldException e) { return false; }
}

Try / catch

try {
    SessionFactory sf = cfg.buildSessionFactory();
} catch (AnnotationException e) {
    throw new IllegalStateException("Check mappedBy spelling: " + e.getMessage(), e);
}

Prevention

Copy-paste property names from the owning field, never type them from memory
Re-run a mapping smoke test after renaming association fields

When it happens

Trigger: @OneToOne(mappedBy = "usr") where the target entity's field is actually called 'user'; target entity different from the one assumed (targetEntity pointing to the wrong class); property renamed without updating mappedBy; Kotlin/Java name mismatch (field vs accessor naming).

Common situations: Typos in mappedBy values; renaming the owning field via IDE refactor that does not update string-based references; copy-pasting an association between entity pairs; Lombok/records changing the effective property name.

Related errors

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