Fix "Unknown Kotlin JVM target: 21" after Upgrading Android Studio

// 🔍 Common error when upgrading Android Studio
Execution failed for task ':app:kaptGenerateStubsDebugKotlin'.
> Error while evaluating property 'compilerOptions.jvmTarget' of task ':app:kaptGenerateStubsDebugKotlin'.
   > Failed to calculate the value of property 'jvmTarget'.
      > Unknown Kotlin JVM target: 21

Problem: JDK 21 Incompatibility with Kotlin

When upgrading Android Studio from Iguana to LadyBug, projects may fail to compile with an Unknown Kotlin JVM target: 21 error—even if you haven't explicitly configured JDK 21. This happens because:

::list

• Android Studio LadyBug defaults to JDK 21 for new installations
• Kotlin versions before 2.0.0 don't support JVM target 21
• Kapt (Kotlin Annotation Processing) doesn't detect the correct target version
• Compiler confuses JDK 21 runtime with requested JVM target
• Your project's JDK settings might reset during the upgrade ::

Symptoms

• Project compiles fine in Android Studio Iguana but fails in LadyBug
• Build fails during kaptGenerateStubsDebugKotlin task
• Error referencesUnknown Kotlin JVM target: 21 despite jvmTarget = "1.8" in Gradle

Recommended Solutions

1. Configure Project for JDK 17 (Best Practice)

Update your app/build.gradle.kts to explicitly target JDK 17:

android {
    namespace = "com.ollo.stopsindicator"
    compileSdk = 34

    // ... other configurations
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = "17"  // 🔧 Change from "1.8" to "17"
    }
    
    // ... other configurations
}

::list

• Use JavaVersion.VERSION_17 for both sourceCompatibility and targetCompatibility
• Set jvmTarget = "17" (string value) in kotlinOptions
• JDK 17 maintains compatibility with Android API levels
• Sync Gradle after making changes ::

2. Set Correct JDK in Android Studio

1. Go to File > Project Structure
2. Select SDK Location in the left panel
3. Under JDK Version, choose Download JDK
4. Select version 17 with JetBrains Runtime
5. Click Apply and sync project

Alternative Path

Configure via File > Settings > Build, Execution, Deployment > Build Tools > Gradle and set Gradle JDK to a JDK 17 installation

3. Task-Specific JVM Target Override (Advanced)

If you need JDK 21 for other tasks but want to fix kapt, add this to your module-level build.gradle.kts:

// 👇 Add this at the end of your build.gradle.kts
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile> {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
    }
}

::list

• Modules only: Apply to modules where kapt is used
• Version check: Ensure your Kotlin version supports JvmTarget.JVM_17
• No JDK change: Maintains JDK 21 for other tasks ::

4. Update Kotlin and Plugins

In your project-level build.gradle.kts, ensure you're using compatible versions:

dependencies {
    classpath("com.android.tools.build:gradle:8.3.0")
    classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21") // 🚀 Update to ≥2.0.0
    // ... other classpaths
}

::list

• Kotlin 2.0.0+ adds JDK 21 support
• Also update Compose compiler if used: kotlinCompilerExtensionVersion = "1.5.7"
• Check latest versions on Kotlin Releases ::

Why JDK 17 Instead of 1.8?

While reverting to jvmTarget = "1.8" might work, we recommend JDK 17 because:

::list

• Long-term support: JDK 17 is LTS release
• Modern language features: Records, sealed classes, etc.
• Performance improvements: Up to 20% runtime improvements
• Package visibility: Better handling for Android 13+
• Kotlin future-proof: New Kotlin features target JDK 17+
• Google's recommendation: Required for Android Studio Giraffe+ ::

Compatibility Check

Android minSdk 26+ supports all JDK 17 features. For older projects targeting Android 21-25:

• Continue using jvmTarget = "1.8" temporarily
• Plan migration to raise minSdk to 26+

Preventing Future JDK Conflicts

1. Lock JDK version in gradle.properties:

org.gradle.java.home=/path/to/jdk17

2. Update regularly: Check Android Studio updates quarterly
3. Verify settings: After major IDE updates, confirm:
   • Project Structure > JDK Location
   • Gradle JDK configuration
   • Kotlin plugin version compatibilities

When Nothing Works

If all solutions fail:

1. Downgrade Android Studio to Iguana/previous version temporarily
2. File issue at Kotlin Issue Tracker with:
   • Full Gradle file
   • Kotlin version
   • ./gradlew --version output
3. Consider migrating from kapt to KSP

   // Replace in build.gradle.kts
   id("com.google.devtools.ksp") version "1.9.21-1.0.16" 
   // Remove: id("org.jetbrains.kotlin.kapt")

::: success Final Check After applying fixes, verify with:

./gradlew clean && ./gradlew kaptDebugKotlin

:::

By configuring explicit JDK 17 settings and updating Kotlin versions, this compatibility error resolves while maintaining modern development capabilities.