[build] Gradle과 Kotlin Kapt 버전 충돌 문제 해결 가이드

예전에 개발했던 오래된 프로젝트 다시 실행해보면 종종 발생하는 에러

 

🚀 개요

Android 개발을 하다 보면 Gradle과 Kotlin Kapt 버전 간의 충돌로 인해 빌드 오류가 발생하는 경우가 있습니다. 특히 다음과 같은 오류 메시지가 나타날 수 있습니다.

A problem occurred configuring project ':app'.
> Could not create task ':app:kaptDebugKotlin'.
> Cannot use @TaskAction annotation on method KaptWithoutKotlincTask.compile() because interface org.gradle.api.tasks.incremental.IncrementalTaskInputs is not a valid parameter to an action method.

이 오류는 Gradle과 Kotlin Kapt의 버전이 맞지 않거나, 특정 Gradle API가 변경된 경우 발생할 가능성이 높습니다. 이번 글에서는 이 문제의 원인과 해결 방법을 상세히 정리해보겠습니다.

---

🧐 원인 분석

1. 오류 메시지 해석

• Could not create task ':app:kaptDebugKotlin' → Gradle이 kaptDebugKotlin 태스크를 생성하는 과정에서 실패함
• Cannot use @TaskAction annotation on method KaptWithoutKotlincTask.compile() → Gradle의 @TaskAction 어노테이션이 잘못 사용됨
• IncrementalTaskInputs is not a valid parameter to an action method → Gradle에서 더 이상 IncrementalTaskInputs을 지원하지 않음

이 오류는 일반적으로 Gradle과 Kotlin Kapt의 호환성 문제로 인해 발생합니다. 해결을 위해 Gradle, Kotlin, Hilt 등의 버전을 조정해야 합니다.

---

🛠️ 해결 방법

1. Gradle 버전 확인 및 업데이트

현재 사용 중인 Gradle 버전을 확인하고 최신 버전으로 업데이트하세요. gradle-wrapper.properties 파일에서 다음과 같이 설정할 수 있습니다.

distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip

Gradle 버전을 변경한 후 **"Sync Project with Gradle Files"**를 실행하세요.

2. Kotlin 버전 확인 및 업데이트

Kotlin 버전도 최신 버전으로 유지해야 합니다. build.gradle.kts (Project 수준)에서 확인할 수 있습니다.

buildscript {
    ext.kotlin_version = "1.9.20" // 최신 버전으로 업데이트
}

Kotlin 버전을 변경한 후 **"Sync Project with Gradle Files"**를 실행하세요.

3. Kapt 플러그인 적용 여부 확인

build.gradle.kts (Module 수준)에서 Kapt 플러그인이 적용되어 있는지 확인하세요.

plugins {
    id("kotlin-kapt")
}

4. Hilt 버전 업데이트 (사용하는 경우)

Hilt를 사용 중이라면 버전이 Kotlin 및 Gradle과 호환되는지 확인해야 합니다.

dependencies {
    implementation("com.google.dagger:hilt-android:2.48.1")
    kapt("com.google.dagger:hilt-compiler:2.48.1")
}

5. Gradle, Kotlin, Kapt, Hilt의 호환 가능한 버전 조합 적용

호환되지 않는 버전 조합을 사용하면 위와 같은 오류가 발생할 수 있습니다. 공식 문서를 참고하여 최신 버전 조합을 적용하세요.

6. 프로젝트 정리 및 캐시 삭제

변경 사항을 적용한 후 아래 단계를 수행하세요.

1. "Clean Project" 실행
2. "Rebuild Project" 실행
3. "Invalidate Caches / Restart..." 실행

---

💡 추가 해결 방법

1. gradle.properties에서 Kapt 관련 설정 추가

kapt.includeCompileClasspath=false

이 설정을 추가하면 Kapt가 이전 버전의 Gradle과 더 잘 호환될 수 있습니다.

2. build.gradle.kts에서 Kapt 옵션 추가

kapt {
    useBuildCache = true
    correctErrorTypes = true
    useWorkerApi = true
}

이 설정을 추가하면 Kapt가 최신 Gradle API를 활용하여 빌드 안정성을 높입니다.

---

✅ 최적의 버전 조합 예시

도구 권장 버전

Gradle	8.0
Kotlin	1.9.20
Hilt	2.48.1

---

📌 결론

Gradle과 Kotlin Kapt 버전 충돌 문제는 주로 버전 간 호환성 문제로 인해 발생합니다. 위에서 소개한 방법들을 적용하여 Gradle, Kotlin, Hilt 등의 버전을 조정하면 대부분의 오류를 해결할 수 있습니다. 또한, 프로젝트를 정리하고 캐시를 삭제하는 것도 문제 해결에 큰 도움이 됩니다. 😊

---

🔗 참고 자료

• Gradle 공식 문서
• Kotlin 공식 문서
• Hilt 공식 문서
• Stack Overflow: 관련 오류 해결 방법