JPA mappedBy reference an unknown target entity 오류 원인과 해결 방법
JPA로 @OneToMany / @ManyToOne 양방향 매핑을 구현하다 보면 다음과 같은 오류를 한 번쯤은 만나게 됩니다.
mappedBy reference an unknown target entity property
특히 아래와 같이 mappedBy="parentVO"와 같이 지정한 경우,
필드명 / 매핑 관계 / 엔티티 설정에 조금만 틀어져도 이 오류가 바로 발생합니다.
1. 예제 코드 구조 (Parent & Child)
질문에서 사용한 구조를 먼저 정리해보면 다음과 같습니다.
A Class (Parent)
@Entity
public class Parent {
@Id
@GeneratedValue
private Long parentSeq;
@OneToMany(mappedBy = "parentVO")
private List<Child> rsrcGuildsList;
// getter / setter ...
}
B Class (Child)
@Entity
public class Child {
@Id
@GeneratedValue
private Long childSeq;
@ManyToOne(optional = false)
@JoinColumn(name = "parent_seq", updatable = false, insertable = false)
private Parent parentVO;
// getter / setter ...
}
Parent에서는 @OneToMany(mappedBy="parentVO")를 통해
Child 쪽의 parentVO 필드를 바라보도록 설정했고,
Child에서는 @ManyToOne + @JoinColumn(name = "parent_seq")로
부모 키를 참조하도록 되어 있습니다.
그런데 이때 JPA가 다음과 같은 메시지를 뿜을 수 있습니다.
mappedBy reference an unknown target entity property: Child.parentVO
즉, mappedBy로 적어준 "parentVO"를 Child 엔티티에서 제대로 찾지 못했다는 의미입니다.
2. mappedBy reference an unknown target entity 오류 의미
@OneToMany(mappedBy="...") 에서 mappedBy는
반대편 엔티티에서 이 관계를 관리하는 “필드명”을 의미합니다.
- Parent 입장:
@OneToMany(mappedBy="parentVO")→ Child 안의parentVO필드를 바라봄 - Child 입장:
@ManyToOne으로 실제 외래키(parent_seq)를 관리
그런데 JPA가 스캔을 해보니:
- Child 클래스가 엔티티(@Entity)로 인식되지 않았거나
- Child 클래스 안에
parentVO라는 필드가 없거나 - 필드는 있지만, 연관관계 필드로 제대로 인식되지 않는 경우
이런 상황에서 "mappedBy reference an unknown target entity" 오류가 발생합니다.
3. 가장 흔한 원인 정리
3-1. Child 엔티티에 @Entity 누락
Child 클래스에 @Entity가 빠져 있으면,
JPA 입장에서는 Child 자체를 엔티티로 인식하지 못합니다.
@Entity // ✅ 이게 빠져 있으면 mappedBy에서 인식을 못함
public class Child {
...
}
3-2. mappedBy 값과 필드명 불일치
Parent에서 mappedBy = "parentVO"라고 적었다면,
Child 엔티티 안에는 꼭 “parentVO”라는 이름의 필드가 존재해야 합니다.
- 필드명이
parent,parentEntity등으로 다른데mappedBy="parentVO"로 적은 경우 - 대소문자 차이 (
parentVovsparentVO)
이런 경우에도 동일 오류가 발생합니다.
3-3. JoinColumn / insertable / updatable 설정 문제
Child 쪽에서 @JoinColumn(name="parent_seq", updatable=false, insertable=false)로
둘 다 false를 걸어둬서 JPA가 이 필드를 연관관계 주인으로 인식하지 못하는 경우도 있습니다.
일반적인 양방향 매핑에서는 다음과 같이 Child 쪽이 연관관계 주인이 되도록 설정합니다.
@ManyToOne(optional = false)
@JoinColumn(name = "parent_seq") // ⭐ insertable / updatable 기본값 true
private Parent parentVO;
그리고 Parent는 단순히 읽기용(역방향) 컬렉션으로만 사용하고
mappedBy를 통해 연관관계 주인(Child)을 가리키게 합니다.
4. 추천 매핑 예제 (정리된 버전)
Parent 엔티티 예시
@Entity
public class Parent {
@Id
@GeneratedValue
private Long parentSeq;
@OneToMany(mappedBy = "parentVO")
private List<Child> rsrcGuildsList = new ArrayList<>();
// 양방향 편의 메서드 (선택)
public void addChild(Child child) {
rsrcGuildsList.add(child);
child.setParentVO(this);
}
// getter / setter ...
}
Child 엔티티 예시
@Entity
public class Child {
@Id
@GeneratedValue
private Long childSeq;
@ManyToOne(optional = false)
@JoinColumn(name = "parent_seq") // 외래키 컬럼
private Parent parentVO;
// getter / setter ...
}
위처럼 구성하면 mappedBy="parentVO"는
Child 엔티티의 parentVO 필드를 정확히 바라보게 되고,
mappedBy reference an unknown target entity 오류 없이 정상 매핑됩니다.
5. 디버깅 체크리스트
이 오류가 발생했을 때 아래 항목을 하나씩 체크해보세요.
- ✅ Child 클래스에
@Entity가 선언되어 있는가? - ✅
mappedBy에 적은 이름과 Child의 필드명이 정확히 일치하는가? (대소문자 포함) - ✅ Child 쪽 연관관계 필드에
@ManyToOne또는@OneToOne이 붙어 있는가? - ✅
@JoinColumn설정이 너무 과도하게insertable=false, updatable=false로 막혀 있지는 않은가? - ✅ Parent/Child 둘 다 같은 패키지 또는 같은 persistence-unit에 포함되어 있는가?
6. 정리
mappedBy reference an unknown target entity 오류는 대부분 필드명 불일치, 엔티티 인식 실패, 연관관계 주인 설정 문제에서 시작됩니다.
mappedBy는 “반대편 엔티티의 연관관계 필드명”이라는 점을 꼭 기억하기- Child 쪽이 외래키를 직접 가지는 연관관계 주인이 되도록 설계하기
- @Entity, @JoinColumn, insertable/updatable 설정을 다시 한 번 점검하기
위 예제와 체크리스트를 기준으로 코드를 정리하면 JPA 양방향 매핑에서 발생하는 mappedBy 관련 오류를 훨씬 수월하게 해결할 수 있습니다.
댓글
댓글 쓰기