Gradle "Could not resolve dependencies" 에러 6가지 원인 5분 해결

빌드 로그에 빨간 글씨로 이런 게 뜨면 심장이 철렁합니다.

* What went wrong:
Could not resolve all files for configuration ':app:runtimeClasspath'.
> Could not find com.example:some-lib:1.2.3.
> Could not resolve com.squareup.okhttp3:okhttp:4.12.0.

결론부터 말하면 이 세 가지 에러 원문은 사실상 한 묶음입니다. "원하는 좌표의 jar를 어디서도 못 받아왔다"는 같은 사건을 Gradle이 단계별로 다르게 표현할 뿐이죠. 개념 설명은 걷어내고, 에러 → 진단 명령 → 복붙 코드 순으로 바로 고쳐봅시다.

30초 진단 플로우차트와 만능 첫 명령

뭘 의심하든 일단 이 두 명령부터 돌립니다.

# 1) 의존성 트리와 어떤 저장소를 뒤졌는지 상세 로그로 확인
./gradlew dependencies --info

# 2) 캐시 무시하고 강제로 다시 받아오기 (캐시 손상이면 이걸로 끝남)
./gradlew build --refresh-dependencies

로그를 읽으며 아래로 분기하세요.

원인 1 — 저장소 블록 누락 / jcenter() 폐기

가장 흔합니다. JCenter는 2021년부터 서비스가 종료되어 지금은 응답하지 않습니다. 레거시 빌드에 아직 jcenter()가 남아 있으면 그대로 깨집니다.

진단:

./gradlew dependencies --info | grep -i "repositor\|jcenter"

수정 (Groovy DSL):

// build.gradle - 수정 전
repositories {
    jcenter()   // ❌ 종료됨
}

// 수정 후
repositories {
    mavenCentral()
    google()    // Android 의존성(androidx 등)이라면 필수
}

Kotlin DSL:

// build.gradle.kts
repositories {
    mavenCentral()
    google()
}

repositories 블록 자체가 없으면 Gradle은 아무 데서도 못 찾습니다. AGP 버전업 후 androidx를 못 찾는다면 십중팔구 google() 누락이에요.

원인 2 — 사내 Nexus / Artifactory 인증·프록시

사내 저장소는 인증이 막혀 401/403이 나면서 "Could not find"로 둔갑합니다. 자격증명은 코드에 박지 말고 gradle.properties로 분리하세요.

# ~/.gradle/gradle.properties (개인 홈, 커밋 금지)
nexusUser=your-id
nexusPassword=your-token

// build.gradle.kts
repositories {
    maven {
        url = uri("https://nexus.mycorp.com/repository/maven-public/")
        credentials {
            username = providers.gradleProperty("nexusUser").get()
            password = providers.gradleProperty("nexusPassword").get()
        }
    }
    mavenCentral()
}

실무 팁: 저는 사내망에서 깨질 때마다 curl -u id:token https://nexus.../path/to.jar로 jar를 직접 받아봅니다. curl이 받으면 Gradle 설정 문제, curl도 401이면 권한·토큰 문제로 5초 만에 갈립니다.

원인 3 — 버전·좌표 오타 / BOM 미적용

com.example:lib:1.2.3에서 group이나 version 한 글자만 틀려도 "Could not find artifact"입니다. 버전을 여러 모듈에 흩뿌려 관리하다 어긋나는 경우도 많은데, 이때 BOM(platform())으로 정렬하면 깔끔합니다.

dependencies {
    // BOM으로 버전 일괄 고정 → 개별 버전 생략 가능
    implementation(platform("com.fasterxml.jackson:jackson-bom:2.17.1"))
    implementation("com.fasterxml.jackson.core:jackson-databind") // 버전 X

    // 강제 정렬이 필요하면 enforcedPlatform
    implementation(enforcedPlatform("org.springframework.boot:spring-boot-dependencies:3.3.0"))
}

진단은 특정 모듈·configuration만 콕 집어서:

./gradlew :app:dependencies --configuration runtimeClasspath

원인 4 — 방화벽·프록시·SSL 인증서

unable to find valid certification path to requested target가 보이면 사내 CA가 JDK에 등록 안 된 상태입니다. 프록시 설정부터:

# gradle.properties
systemProp.https.proxyHost=proxy.mycorp.com
systemProp.https.proxyPort=8080
systemProp.https.nonProxyHosts=*.mycorp.com|localhost
systemProp.http.proxyHost=proxy.mycorp.com
systemProp.http.proxyPort=8080

사내 CA 인증서를 JDK cacerts에 등록:

keytool -importcert -alias mycorp-ca \
  -file mycorp-ca.crt \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit

같은 SSL 증상을 다른 도구에서 만났다면(예: "unable to get local issuer certificate") 해당 전용 글을 참고하세요. 여기서는 Gradle/JDK 신뢰 저장소 관점만 다룹니다.

원인 5 — Gradle 캐시 손상

"어제까지 됐는데"의 주범. 데몬 중지 후 모듈 캐시만 지우는 게 안전합니다.

# 1) 데몬 정지 (파일 잠금 해제)
./gradlew --stop

# 2) 모듈 캐시만 삭제 (전체 ~/.gradle 통째로 지우지 말 것)
rm -rf ~/.gradle/caches/modules-2

# 3) 강제 재다운로드
./gradlew build --refresh-dependencies

IntelliJ/Android Studio라면 File → Invalidate Caches / Restart를 병행하세요. IDE 캐시와 Gradle 캐시는 별개라 한쪽만 지우면 또 깨집니다.

원인 6 — 멀티모듈 / 플러그인 저장소 분리

Gradle 8.x는 FAIL_ON_PROJECT_REPOS가 기본이라 모듈마다 repositories를 두면 거부합니다. 저장소는 settings.gradle(.kts)에서 중앙 관리하세요. 플러그인용과 의존성용 저장소는 블록이 다릅니다.

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

에러 메시지에 :moduleA: 같은 모듈 경로가 찍혔다면 여기를 가장 먼저 의심하세요.

결론: 증상 → 명령 → 수정 한 줄 체크리스트

빠른 라우팅: artifact가 보이면 원인 1·3부터, 모듈 경로(:module:)가 보이면 6번부터 보면 됩니다.

참고: npm ERESOLVE, pip ResolutionImpossible, Python ModuleNotFoundError 등 다른 생태계의 비슷한 의존성 에러는 스택과 해결 각도가 완전히 달라 각각의 전용 글로 분리해 두었습니다.

자주 묻는 질문 (FAQ)

Q. --refresh-dependencies를 써도 계속 "Could not find"가 떠요. A. 캐시가 아니라 저장소·좌표 문제일 가능성이 큽니다. ./gradlew dependencies --info로 Gradle이 실제로 어떤 URL을 뒤졌는지 확인하고, 그 저장소에 jar가 실재하는지 브라우저나 curl로 직접 검증하세요.

Q. ~/.gradle 폴더를 통째로 지워도 되나요? A. 권장하지 않습니다. wrapper 배포본·전역 설정까지 날아갑니다. ./gradlew --stop 후 ~/.gradle/caches/modules-2만 삭제하는 게 안전합니다.

Q. Gradle 8에서 build.gradle에 repositories를 넣었더니 빌드가 거부돼요. A. FAIL_ON_PROJECT_REPOS 기본값 때문입니다. 저장소를 settings.gradle(.kts)의 dependencyResolutionManagement 블록으로 옮기면 해결됩니다.