Unknown Kotlin JVM target: 21 in Android Studio

Problem Statement

After updating to Android Studio Ladybug (2024.2.x), many developers encounter the error "Unknown Kotlin JVM target: 21" during project compilation. This error typically appears despite having the following configurations in your build.gradle file:

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

kotlinOptions {
    jvmTarget = "17"
}

This issue arises because after the update:

1. Android Studio may reset the Gradle JDK to an incompatible version (like JDK 21)
2. Kotlin toolchain configurations may become misaligned
3. Outdated Kotlin plugins struggle with the new JDK toolchain

WARNING

The error message references JVM target 21 even when your configuration specifies 17, indicating a JDK compatibility mismatch in the build environment.

Solutions

1. Configure Gradle JDK Settings

Set the Gradle JDK to JetBrains Runtime 17 in Android Studio:

1. Navigate to File > Settings > Build, Execution, Deployment > Gradle
2. Under Gradle JDK, select jbr-17 (JetBrains Runtime 17)
3. Click Apply

2. Update build.gradle Configurations

Add explicit Kotlin JVM toolchain configuration to your module-level build.gradle.kts:

android {
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = "17"
    }
    // Add this block
    kotlin {
        jvmToolchain(17)
    }
}

For Groovy users (build.gradle):

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

3. Update Plugins and Dependencies

Ensure compatibility by updating plugins in your top-level build.gradle:

// Top-level build.gradle.kts
plugins {
    id("com.android.application") version "8.7.1" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// Explicitly declare Kotlin Gradle plugin version
buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21")
    }
}

For gradle-wrapper.properties, use compatible Gradle versions:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-all.zip

TIP

If using KSP instead of kapt, update to:
id("com.google.devtools.ksp") version "2.0.0-1.0.22"

4. Finalize Configuration

1. Delete .gradle folder in your project root
2. Resync Gradle projects (elephant icon in toolbar)
3. Rebuild project via Build > Rebuild Project

Common Solution Patterns

Configuration Area	Key Settings
Gradle JDK	JetBrains Runtime 17
Kotlin Plugin	2.0.0+ (1.9.20 minimum)
Android Gradle Plugin	8.3.2+ (8.7.1 recommended)
Gradle Wrapper	8.10.2 (compatible with AGP 8.x)

Important Considerations

1. Avoid downgrading Android Studio - Solutions requiring IDE downgrades (e.g., to 2024.1) are temporary workarounds
2. Clean after configuration changes - Always delete .gradle and build folders after major configuration updates
3. Multi-module projects - Apply toolchain settings consistently across all modules

DANGER

Never set jvmTarget to "21" unless you've explicitly:

1. Set Gradle JDK to a Java 21 compatible runtime
2. Updated Kotlin plugin to version that supports JVM 21
3. Changed all Java/Kotlin compatibility blocks to VERSION_21

Why These Solutions Work

The kotlin { jvmToolchain(17) } directive explicitly configures Kotlin compiler tasks to use the JDK 17 toolchain, bypassing Android Studio's default JDK settings. Combined with updated plugin versions, this ensures Kotlin's compiler recognizes your JVM target configuration.

For most projects, implementing both Gradle JDK 17 setting and explicit toolchain configuration resolves the "Unknown target: 21" error permanently. If issues persist, verify runtime Java versions using ./gradlew -v in terminal.