# Gradle JVM Toolchain — Java-21-Only System Fix

## Problem

A Gradle project requires Java 17 (via `jvmToolchain(17)` or `JVM_17` in `compilerOptions`), but only Java 21 is installed on the build machine. Errors like:

```
Cannot find a Java installation on your machine matching this tasks requirements: {languageVersion=17}
```

Or after switching source/target to 21:

```
Inconsistent JVM-target compatibility detected for tasks 'compileDebugJavaWithJavac' (21) and 'compileDebugKotlin' (17).
```

## Root Cause

Android projects commonly specify Java 17 in three places:

1. **`compileOptions` block** — `sourceCompatibility = VERSION_17`, `targetCompatibility = VERSION_17`
2. **`kotlin` block** — `jvmTarget.set(JVM_17)` via `compilerOptions`
3. **`kotlinOptions` block** (legacy) — `jvmTarget = "17"`
4. **Top-level `kotlin { jvmToolchain(17) }`** — for non-Android modules

When all three aren't consistently set to 21, you get the JVM-target mismatch error.

## Fix — Change ALL Four Places

Search across all modules for Java 17 references:

```bash
grep -rn "VERSION_17\|jvmToolchain(17)\|JVM_17" . --include="*.kts"
```

### 1. `compileOptions` (Android modules)

```
sourceCompatibility = JavaVersion.VERSION_17  →  JavaVersion.VERSION_21
targetCompatibility = JavaVersion.VERSION_17  →  JavaVersion.VERSION_21
```

### 2. `compilerOptions` (Android and pure-Kotlin modules)

```
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
→
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
```

### 3. `kotlinOptions` (legacy `android { }` block)

```
kotlinOptions { jvmTarget = "17" }
→
kotlinOptions { jvmTarget = "21" }
```

### 4. `kotlin { jvmToolchain(...) }` (non-Android modules like `:domain`)

```
kotlin { jvmToolchain(17) }
→
kotlin { jvmToolchain(21) }
```

### Verify

```bash
grep -rn "VERSION_17\|jvmToolchain(17)\|JVM_17" . --include="*.kts"
# Should return zero matches
```

### Clean build

```bash
rm -rf */build .gradle build
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
./gradlew assembleDebug
```

## Pitfalls

- **The `compilerOptions` block overrides `kotlinOptions`** — both must agree on 21, or you get the mismatch error.
- **Configuration cache** caches JVM target values. If you change versions, delete `.gradle/` and all `*/build/` directories before retrying.
- **The `domain` module uses `jvmToolchain()` syntax** — this is separate from `compileOptions` and must be updated independently.
- **Do NOT install a second JDK** — just patch all references to match the installed version. This is simpler and the Kotlin 2.x compiler works fine with Java 21.