Maven Dependencies를 가져오지 못할 때 어디부터 봐야 하는가

Maven 프로젝트를 열었는데 의존성이 내려받아지지 않으면, 처음에는 단순히 IDE 문제처럼 보일 수 있다. 하지만 실제 원인은 저장소 설정, 네트워크, 프록시, 로컬 캐시, 버전 좌표 오류 등 다양하다.

가장 먼저 확인할 것

• groupId, artifactId, version이 맞는가
• 중앙 저장소나 사설 저장소에 실제로 존재하는가
• 네트워크나 프록시 제한이 있는가
• 로컬 캐시가 깨져 있지는 않은가

IDE 문제와 빌드 문제를 구분하기

중요한 것은 IDE 화면이 아니라 CLI 빌드다.

mvn dependency:resolve나 mvn clean compile이 실패하면 실제 의존성 문제이고, CLI는 되는데 IDE만 안 되면 인덱싱이나 프로젝트 동기화 문제일 가능성이 크다.

자주 나오는 원인

잘못된 버전 좌표

오타가 있거나 존재하지 않는 버전을 적으면 당연히 내려받지 못한다.

사설 저장소 설정 누락

회사 환경에서는 Nexus나 Artifactory를 거치는 경우가 많다. 이 저장소 설정이 빠지면 외부에서는 존재하는 라이브러리도 내부 환경에서 못 받을 수 있다.

로컬 캐시 손상

.m2 아래에 깨진 아티팩트가 남아 있으면 반복적으로 실패할 수 있다. 이 경우 특정 디렉터리만 지우고 다시 받는 것이 전체 삭제보다 안전하다.

프록시와 인증 문제

사내망, VPN, 프록시 인증이 개입되면 저장소 접근 자체가 막힐 수 있다.

정리

Maven 의존성 문제는 IDE를 다시 켜는 것으로 끝나지 않는 경우가 많다. 좌표, 저장소, 캐시, 네트워크를 순서대로 나눠 보면 대부분의 원인을 좁힐 수 있다.