Fixing "Unresolved reference kapt and ksp" in Android Room Setup

Problem Statement

When setting up Room for local database in Android Studio with Kotlin, developers may encounter "Unresolved reference kapt" and/or "Unresolved reference ksp" errors in their build.gradle.kts (Module: app) file. These errors occur when the annotation processing plugins aren't properly configured, preventing Room from generating necessary implementation code during compilation. The issue typically appears after adding Room dependencies to the build file.

What Are kapt and ksp?

• kapt (Kotlin Annotation Processing Tool): Legacy Kotlin compiler plugin enabling Java annotation processors to work with Kotlin code
• ksp (Kotlin Symbol Processing): Modern replacement for kapt that processes Kotlin symbols directly, offering:
  • 2x faster compilation
  • Better Kotlin type awareness
  • Generated Kotlin code instead of Java

Solutions: Choosing kapt or ksp

WARNING

Never use both kapt and ksp simultaneously for the same Room compiler - choose either processor

Option 1: Use kapt (Simpler Setup)

// Add the kapt plugin in your module-level build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("kotlin-kapt")   // Apply kapt plugin
}

dependencies {
    val room_version = "2.6.1"
    implementation("androidx.room:room-runtime:$room_version")
    implementation("androidx.room:room-ktx:$room_version")
    kapt("androidx.room:room-compiler:$room_version")  // Use kapt

    // Remove other room-compiler references 
    // including annotationProcessor and ksp
}

Option 2: Use ksp (Recommended - Better Performance)

// In project-level build.gradle.kts
plugins {
    id("com.android.application") version "8.3.2" apply false
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
    id("com.google.devtools.ksp") version "1.9.21-1.0.15" apply false
}

// In module-level build.gradle.kts
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")  // Apply ksp plugin
}

dependencies {
    val room_version = "2.6.1"
    implementation("androidx.room:room-runtime:$room_version")
    implementation("androidx.room:room-ktx:$room_version")
    ksp("androidx.room:room-compiler:$room_version")  // Use ksp

    // Remove other room-compiler references 
    // including annotationProcessor and kapt
}

After making these changes:

1. Sync Gradle files in Android Studio
2. Clean project (Build > Clean Project)
3. Rebuild project (Build > Rebuild Project)

Common Mistakes to Avoid

1. Duplicate processors: Removing old references is crucial

   // BEFORE (Problematic):
   annotationProcessor("androidx.room:room-compiler:$room_version")
   kapt("androidx.room:room-compiler:$room_version")
   ksp("androidx.room:room-compiler:$room_version")
   
   // AFTER (Correct):
   // Only one processor remains!
   ksp("androidx.room:room-compiler:$room_version")

2. Plugin version mismatch: Ensure KSP version matches your Kotlin version

   • Find compatible versions: KSP GitHub Releases

3. Missing apply plugin: Ensure the plugin is applied in module's build.gradle.kts

   // Module-level plugins MUST include:
   id("com.google.devtools.ksp")  // For ksp
   // OR
   id("kotlin-kapt")              // For kapt

Best Practices

1. Migrate to ksp for faster builds (room-compiler supports ksp since Room 2.4.0)
2. Remove unused Room extensions (RxJava, Guava) if not needed
3. Verify version compatibility:

   // Good practice - keep versions consistent
   plugins {
       id("org.jetbrains.kotlin.android") version "1.9.0"
       id("com.google.devtools.ksp") version "1.9.21-1.0.15"
   }

📘 Official Documentation:
Android Room with Kotlin
Migrate from kapt to ksp