Resolving java.lang.IllegalAccessError with Kotlin KAPT and Firebase

Problem Statement

When adding Firebase Database dependencies to an Android project using Kotlin and KAPT (Kotlin Annotation Processing Tool), you may encounter the following error:

java.lang.IllegalAccessError: superclass access check failed: 
class org.jetbrains.kotlin.kapt3.base.javac.KaptJavaCompiler (in unnamed module @0x52cfe3c1) 
cannot access class com.sun.tools.javac.main.JavaCompiler (in module jdk.compiler) 
because module jdk.compiler does not export com.sun.tools.javac.main to unnamed module @0x52cfe3c1

This error typically occurs after adding implementation("com.google.firebase:firebase-database") to a project that previously worked with Firebase Analytics and Authentication. The error indicates a Java module access conflict between the Kotlin KAPT compiler and the JDK's internal tools.

Common triggers:

• Recent updates to Firebase dependencies
• Using incompatible Kotlin/JDK versions
• Conflicts with annotation processing tools like KAPT and Dagger/Hilt
• Android Studio/Gradle updates

Recommended Solutions

1. Update Kotlin and Related Dependencies (Recommended)

This issue was fixed in Kotlin 1.9.21. Update your Kotlin plugins and libraries:

1. In your project-level build.gradle.kts:

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.21" apply false
    // Other plugins...
}

2. Specify consistent Kotlin versions:

// Top-level build.gradle.kts
buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.21")
    }
}

3. In your app-level build.gradle.kts:

dependencies {
    implementation("org.jetbrains.kotlin:kotlin-stdlib:1.9.21")
    implementation("org.jetbrains.kotlin:kotlin-reflect:1.9.21")
}

4. Sync Gradle and clean your project:

./gradlew clean build

Compatibility Notes

• Use JDK 17 with Kotlin 1.9.+
• Ensure Android Gradle Plugin (AGP) version 8.1.0+
• Firebase BOM should be 32.6.0+

2. Migrate from KAPT to KSP (Future-Proof Solution)

Google recommends migrating to KSP for better performance and Java compatibility:

1. Replace kapt with ksp in your build.gradle:

plugins {
    id("com.google.devtools.ksp") version "1.9.21-1.0.15" apply true
    // Remove kotlin-kapt
}

2. Update annotation processors to KSP:

dependencies {
    // Replace kapt dependencies with ksp
    ksp("androidx.room:room-compiler:2.6.0")
    // Remove: kapt("androidx.room:room-compiler:2.6.0")
}

3. Configure JDK compatibility:

kotlin {
    jvmToolchain(17)
}

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

Official Migration Guide

3. Stop Gradle Daemons and Clean Build

Stale processes can cause conflicts:

# Terminal commands
./gradlew --stop          # Stop Gradle daemons
./gradlew clean build     # Clean and rebuild

For Windows PowerShell:

Stop-Process -Name "kotlin-compiler*" -Force
Stop-Process -Name "gradle*" -Force

After stopping processes:

• Clean project in Android Studio (Build > Clean Project)
• Rebuild project (Build > Rebuild Project)

4. Configure JDK Version Compatibility

Ensure consistent Java versions:

1. In app/build.gradle.kts:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
}

2. Verify JDK settings in Android Studio:
   • File > Project Structure > SDK Location
   • Ensure JDK 17 is selected in Gradle settings
   • Check JDK version: File > Settings > Build, Execution, Deployment > Build Tools > Gradle

Validate Java version:

java --version
# Should show: java 17.x.x

Additional Fixes If Issues Persist

Update navigation-safe-args plugin

// Project-level build.gradle.kts
dependencies {
    classpath("androidx.navigation:navigation-safe-args-gradle-plugin:2.8.2")
}

Update Dependency Versions

Example compatible configuration:

// app/build.gradle.kts
dependencies {
    implementation(platform("com.google.firebase:firebase-bom:32.8.0"))
    implementation("com.google.firebase:firebase-auth")
    implementation("com.google.firebase:firebase-database")
    implementation("androidx.navigation:navigation-fragment-ktx:2.7.7")
}

Final Troubleshooting Steps

1. Restart your machine: Clears lingering processes
2. Invalidate Android Studio caches: File > Invalidate Caches
3. Update Android Studio: Ensure you're using latest stable version
4. Check dependency conflicts:

   ./gradlew :app:dependencies

Temporary Workaround (Last Resort)

If immediate build is necessary, add to gradle.properties:

org.gradle.jvmargs=--add-opens jdk.compiler/com.sun.tools.javac.main=ALL-UNNAMED

This bypasses module restrictions but is not a long-term solution. Migrate to KSP instead.

Prevention Best Practices

1. Keep dependencies consistently updated:

   // Top-level build.gradle.kts
   buildscript {
       dependencies {
           classpath("com.android.tools.build:gradle:8.4.2")
           classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.21")
       }
   }

2. Use BOMs for library consistency:

   implementation(platform("com.google.firebase:firebase-bom:32.8.0"))

3. Regularly upgrade Kotlin and Gradle versions

4. Replace kapt with ksp for new projects

5. Maintain JDK compatibility (use JDK 17 since 2023)

By following these solutions, you'll resolve the IllegalAccessError while modernizing your build configuration to prevent similar issues. Prioritize the KSP migration for better long-term maintainability.