IntelliJ Maven 의존성 다운로드 안 됨 해결: Offline Mode·settings.xml·캐시 점검

IntelliJ IDEA에서 pom.xml 의존성이 빨갛거나 Could not transfer artifact 오류가 나면 .m2 전체를 지우지 말고 동기화, 오프라인 모드, 실행 환경, settings.xml, 특정 캐시 순서로 확인하세요.

빠른 결론

먼저 Maven 도구 창에서 Reload All Maven Projects를 누르고 Offline Mode가 꺼져 있는지 확인합니다.
CLI에서는 빌드되는데 IntelliJ에서만 실패하면 Maven home, User settings file, Local repository, Importer JDK를 비교합니다.
캐시가 의심돼도 .m2/repository 전체가 아니라 문제가 있는 의존성만 선택적으로 정리합니다.

확인 기준: 2026년 9월 8일, IntelliJ IDEA Maven 지원 문서 및 Apache Maven 공식 문서

증상별 우선 점검표

증상·오류	먼저 확인할 항목
Dependency not found	Reload, Offline Mode, 저장소에 실제 버전 존재 여부
Could not transfer artifact	인터넷, 프록시, mirror URL, 저장소 접근 권한
PKIX path building failed	사용 JDK와 회사 CA 인증서의 trust store
터미널은 성공, IntelliJ만 실패	Maven home, settings.xml, 로컬 저장소, Importer JDK

1. Maven 프로젝트를 다시 동기화하기

1. IntelliJ IDEA에서 View > Tool Windows > Maven을 엽니다.
2. Maven 도구 창 상단의 Reload All Maven Projects를 누릅니다.
3. 다운로드가 끝난 뒤 pom.xml의 빨간 표시와 Build 창 오류가 사라졌는지 확인합니다.

2. Offline Mode가 켜져 있는지 확인하기

1. Maven 도구 창에서 Toggle Offline Mode가 활성화됐는지 확인합니다.
2. 또는 File > Settings > Build, Execution, Deployment > Build Tools > Maven으로 이동합니다.
3. Work offline이 선택돼 있다면 해제하고 Apply를 누릅니다.
4. 다시 Reload All Maven Projects를 실행합니다.

오프라인 모드는 로컬 저장소의 리소스만 사용하므로 새 의존성을 내려받지 못합니다.

3. IntelliJ의 Maven 실행 환경 맞추기

Settings > Build, Execution, Deployment > Build Tools > Maven에서 다음을 확인합니다.

• Maven home path: 프로젝트에 Wrapper가 있으면 Use Maven wrapper를 검토합니다.
• User settings file·Local repository: CLI와 같은 settings.xml과 .m2/repository인지 봅니다.
• Importing > JDK for importer·Runner > JRE: CLI와 사용 JDK가 같은지 비교합니다.

JDK 비교에는 IntelliJ Gradle JVM 오류와 IDE·빌드 JVM 구분도 참고하세요.

4. settings.xml의 서버·프록시·미러 확인하기

전역 ${maven.home}/conf/settings.xml과 사용자 ${user.home}/.m2/settings.xml이 함께 있으면 사용자 설정이 우선합니다.

1. 사설 저장소의 <server><id>가 repository 또는 mirror ID와 같은지 확인합니다.
2. <proxies>의 host·port와 <mirrors>의 mirrorOf를 관리자 값과 비교합니다.
3. 비밀번호나 토큰을 화면 캡처나 저장소에 노출하지 않습니다.

미러 규칙이나 ID가 어긋나면 정상 요청도 잘못된 서버로 갈 수 있습니다.

5. 손상된 캐시만 선택적으로 다시 받기

특정 그룹과 아티팩트만 실패한다면 프로젝트 폴더의 터미널에서 다음처럼 Maven Dependency Plugin을 사용할 수 있습니다.

mvn dependency:purge-local-repository -Dinclude=그룹ID:아티팩트ID

그룹 ID와 아티팩트 ID를 확인하고, 심벌 표시가 남으면 Cannot resolve symbol 해결 순서를 참고합니다.

주의사항

• .m2/repository 전체 삭제를 첫 해결책으로 쓰지 않습니다.
• PKIX 오류에도 인증서 검증을 끄지 말고 승인된 CA 체인을 JDK trust store에 등록합니다.
• 저장소 계정 정보를 pom.xml이나 공개 Git에 넣지 않습니다.

해결되지 않을 때 추가 점검

1. mvn -version과 빌드로 IntelliJ에서만 실패하는지 구분합니다.
2. 오류 로그에서 실패한 저장소 URL, HTTP 상태 코드, 아티팩트 좌표를 확인합니다.
3. 사내 저장소 상태·권한과 해당 버전의 실제 존재 여부를 관리자에게 확인합니다.

FAQ

Q1. Reload를 눌러도 의존성이 다운로드되지 않는 이유는 무엇인가요?

Offline Mode가 켜졌거나 IntelliJ가 CLI와 다른 settings.xml, 로컬 저장소, JDK를 사용하고 있을 수 있습니다. Maven 설정 화면의 네 항목을 먼저 비교하세요.

Q2. .m2/repository 폴더를 통째로 삭제해도 되나요?

권장하지 않습니다. 정상 캐시까지 지워지므로 문제가 있는 그룹 ID와 아티팩트 ID만 purge하세요.

Q3. PKIX 오류는 SSL 검증을 끄면 해결되나요?

안전한 해결책이 아닙니다. 사용 JDK를 확인하고 승인된 CA 인증서를 올바른 trust store에 등록하세요.

공식 출처

• JetBrains: Maven tool window
• JetBrains: Maven settings
• Apache Maven: purge-local-repository
• Apache Maven: Repository SSL

태그: IntelliJ, Maven, Maven의존성, DependencyNotFound, settings.xml, OfflineMode, 자바개발