Sanniv Khare 6 min read

Kotlin 2.4 to 2.5 RC: what changes in an Android codebase

Kotlin 2.4 to 2.5 RC: what changes in an Android codebase

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.

Compiler flags found in Kotlin 2.4.21 and 2.5.0-RC

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.

Temporary opt-outs in build.gradle.kts while porting to Kotlin 2.5

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. If builder-heavy code (Compose DSLs, Gradle DSLs, coroutine builders) reports new diagnostics, add -XXLanguage:-EliminateSecondKindIncorporation temporarily and file the case with JetBrains.
  6. 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.

Made by the team behind this post

Apps from our studio

  • Goes with this post

    BMDB.fun

    Your Bollywood world at a glance, with links straight to the OTT app that streams each film.

    Android TV · Web · Mobile

    Get
  • Nix

    The Mac uninstaller that finds what the Trash leaves behind: caches, logs, derived data and saved states.

    macOS

    Get
  • Cardigami

    Pop-up greeting cards that rise out of the fold on iPhone Duo.

    iPhone · App Store

    Get
  • OneClick QuitAll

    Quit every running app in one click. See memory and CPU first.

    macOS · Mac App Store

    Get

Need this built? Let’s talk.

We build and run apps for Mac, TV, mobile and the web, and write about what we learn.