Short version: before you move an Android project from Kotlin 2.4.21 (stable since 8 Oct 2026) to 2.5, make sure Gradle and the Kotlin daemon run on JDK 17 or newer. Kotlin 2.5.0-RC, released on 11 Nov 2026, reports an error when the compiler runs on an older JDK. The other default changes (the unused return value checker, name-based destructuring syntax, new type inference) mostly produce new diagnostics rather than broken builds, and each has a documented way back. Kotlin 2.5.0 final is planned for December 2026, so there are a few weeks to prepare.
Why we did this: Peepal and Shopkeeper, our Android apps, are on Kotlin 2.4.x, and we want to know what 2.5 costs before the December release. This post is a table we built from JetBrains’ What’s new in Kotlin 2.5.0-RC page, the release history and the Gradle compatibility table, checked against the compiler distributions of 2.4.21 and 2.5.0-RC from the Kotlin GitHub releases.
The dates
| Version | Date | Source |
|---|---|---|
| 2.4.0 | 3 Jun 2026 | releases |
| 2.4.21 (latest stable) | 8 Oct 2026 | releases |
| 2.5.0-RC | 11 Nov 2026 | EAP build details |
| 2.5.0 | planned December 2026 | releases |
| 2.5.20 | planned March 2027 | releases |
What changes between 2.4.21 and 2.5.0-RC
Every row comes from the 2.5.0-RC page unless linked otherwise. “Default” means on without any flag.
| Change | In 2.5.0-RC | Way back or way in | Hits an Android build? |
|---|---|---|---|
| Compiler needs JDK 17 to run | error when the compiler runs on JDK 8 to 16 | -Xallow-pre-17-runtime-jdk, to be removed in 2.5.20 or 2.6.0 |
yes, if your CI or Gradle JDK is older than 17 |
| Unused return value checker | stable, on by default | -Xreturn-value-checker (present in both compilers) |
new diagnostics where a result is ignored |
| Name-based destructuring, only-syntax mode | default | -Xname-based-destructuring |
no change to existing val (a, b) code |
| Improved type inference | default | -XXLanguage:-EliminateSecondKindIncorporation |
possible different overloads or diagnostics in builder code |
| Cross-module inlining in klib compilation | default | -Xklib-ir-inliner=disabled |
only klib targets (Native, JS, Wasm), not a JVM-only app |
| Companion extensions and blocks | experimental | -Xcompanion-blocks-and-extensions |
only if you opt in |
| Full value classes | experimental | -Xfull-value-classes |
only if you opt in |
| Strict equality for structural classes | opt-in | -Xstrict-equality-for-structural-classes |
only if you opt in |
| Java 28 bytecode | the compiler can emit it | jvmTarget |
no, Android apps target far lower |
Stdlib: onTrue, onFalse, ifOrNull, CodePoint |
experimental | @OptIn(ExperimentalStdlibApi::class) / ExperimentalUnicodeApi |
only if you use them |
Two things the page does not say, so we leave them open: whether the unused return value checker reports warnings or errors in 2.5 (the RC page links to the 2.3 description), and what changes for jvmTarget 1.8 output once the compiler itself needs JDK 17.
The flags, checked in the compilers
Release notes are easy to misread, so we unpacked kotlin-compiler.jar from both official distributions (build.txt reads 2.4.21 and 2.5.0-RC) and searched the compiler argument classes for each flag the page names.

Real output from our test server: three flags are new in 2.5.0-RC, the others already existed in 2.4.21.
The result matches the page: -Xallow-pre-17-runtime-jdk, -Xfull-value-classes and -Xstrict-equality-for-structural-classes are new. -Xreturn-value-checker, -Xname-based-destructuring, -Xklib-ir-inliner and -Xcompanion-blocks-and-extensions were already accepted by 2.4.21; 2.5 changes their defaults or stability, not their spelling.
The help text inside both compilers also explains the destructuring modes better than the release page:
-Xname-based-destructuring=only-syntax: Enables syntax for positional destructuring
with square brackets and the full form of name-based destructuring with parentheses;
-Xname-based-destructuring=name-mismatch: Reports warnings when short form positional
destructuring of data classes uses names that don't match the property names;
-Xname-based-destructuring=complete: Enables short-form name-based destructuring
with parentheses;
only-syntax is the 2.5 default. Per the release page, val (x, y) = point keeps its positional meaning and (val x, val y) = point is the new name-based form. Existing code compiles as before; name-mismatch is the mode to try if you want the compiler to point at destructurings whose names do not match the properties.
The JDK 17 step for Android projects
This is the change most likely to stop a build. The page says 2.5.0-RC “introduces an error as the next step to raising the minimum JDK version required to run the Kotlin compiler from JDK 8 to JDK 17”. It is about the JDK that runs the compiler (the Gradle daemon or the Kotlin daemon), not the bytecode you produce.
Check what your build runs on:
./gradlew --version | grep -E "Launcher JVM|Daemon JVM"
Then fix it in one place rather than per machine: the Gradle daemon toolchain criteria in gradle/gradle-daemon-jvm.properties, org.gradle.java.home in gradle.properties, or the JDK image in CI. Android Studio’s own Gradle JDK setting covers local builds only.

Treat the opt-out flags as a bridge, not a setting to keep: -Xallow-pre-17-runtime-jdk disappears in 2.5.20 or 2.6.0.
Kotlin, AGP and React Native versions together
Kotlin is versioned together with its Gradle plugin, and the compatibility table limits which AGP and Gradle you can pair it with:
| KGP | Gradle | AGP |
|---|---|---|
| 2.4.0 to 2.4.10 | 7.6.3 to 9.5.0 | 8.5.2 to 9.1.0 |
| 2.4.20 to 2.4.21 | 7.6.3 to 9.7.0 | 8.5.2 to 9.3.1 |
| 2.5.x | not in the table yet | not in the table yet |
For React Native projects the framework pins its own Kotlin. In the npm packages, react-native 0.88.1 pins Kotlin 2.2.0 and 0.89.0-rc.1 pins 2.3.21, both with AGP 9.2.1 (we covered that release in React Native 0.89 RC: what changes and what breaks on upgrade). A React Native app is therefore two minor versions behind Kotlin 2.5 and does not need to move first.
Our port order
- Move Gradle, the Kotlin daemon and CI to JDK 17 or newer while still on 2.4.21. Nothing else changes, so any failure is the JDK.
- Check AGP and Gradle against the compatibility table for the Kotlin version you will use. If your AGP is newer than 9.3.1, wait for the 2.5 row.
- Move the Compose compiler Gradle plugin (it shares Kotlin’s version) in the same step, and check that KSP and any other compiler plugin has a release that supports 2.5.
- Switch to 2.5.0-RC on a branch and read the new diagnostics from the unused return value checker. Fix real bugs; mark intentional ignores.
- If builder-heavy code (Compose DSLs, Gradle DSLs, coroutine builders) reports new diagnostics, add
-XXLanguage:-EliminateSecondKindIncorporationtemporarily and file the case with JetBrains. - Leave the experimental flags off in app code until 2.5.0 final.
A Kotlin build of your own project is the real test; the table above tells you where to look first. We will update this page when 2.5.0 final and its compatibility row are published.



