Migrate Android App to Kotlin: 5 Steps (2026)

I was deep in a production incident at 02:13 am. An out‑of‑bounds `ArrayIndexOutOfBoundsException` crashed the checkout flow of our flagship Android app. The stack trace pointed to a hand‑rolled Java singleton that built request headers. The same class was duplicated in three other services, each with a slightly different bug. After we patched the three spots, the crash vanished—but the underlying technical debt was still there, and the panic of that night reminded me why I finally decided to move the whole codebase to Kotlin.

How to migrate a legacy Android app to Kotlin (2026)

To migrate a legacy Java Android app to Kotlin, start by configuring Gradle for mixed‑mode compilation. Use Android Studio’s **Convert Java File to Kotlin** action on discrete modules, beginning with data models and POJOs. Prioritize updating unit tests alongside the conversion to catch nullability issues early, and compile with the K2 compiler for optimal build performance in 2026.

Executive Summary: Why Migrate to Kotlin in 2026?

The Cost of Technical Debt in Legacy Java

Every extra `new StringBuilder()` or manual `equals()` check is a tiny maintenance cost that compounds. In our 2024‑2026 codebase audit, Java‑only modules accounted for 27 % of total crash reports, mostly `NullPointerException`s. The same audit found that boilerplate inflated the method count, pushing us closer to the 64K limit and forcing multidex in places where a clean Kotlin rewrite would have stayed single‑dex.

Kotlin 2.0 and K2 Compiler Benefits

Kotlin 2.0 ships with the K2 compiler, a new front‑end that dramatically speeds up incremental compilation. The Android Developer Summit 2024 reported up to **2× faster** build times for projects that switched the majority of their code to Kotlin and enabled K2. Besides speed, K2 offers tighter null‑safety analysis that surfaces platform‑type mismatches at compile time, which previously slipped into production.

**My take:** If you’re still debating “rewrite vs. migrate,” the numbers speak for themselves. Incremental migration gives you a safety net, while a full rewrite throws away years of battle‑tested logic and test coverage. I’ve seen teams burn months on rewrites only to discover missing edge‑cases that were buried deep in legacy utils.

Pre‑Migration Architecture Audit

Auditing Dependencies for Kotlin Compatibility

Run the Gradle task `./gradlew :app:dependencyInsight –configuration compileClasspath` and pipe the output through a grep for `java.*` to surface jars that haven’t released Kotlin‑friendly APIs. Libraries still stuck on Java 8 surface types like `java.util.Optional` that don’t map cleanly to Kotlin’s nullable types. Where possible, upgrade to their 2025+ releases that already provide Kotlin extensions.

Dependency	Current Version	Kotlin‑Friendly Version	Upgrade Path
Retrofit	2.9.0	2.11.0 (adds `suspend` support)	`./gradlew :app:dependencies` → bump version
RxJava	3.1.5	3.2.0 (adds Kotlin coroutines bridge)	Add `kotlinx-coroutines-rx2`
Dagger	2.44	2.51 (supports Kotlin `@Inject` on objects)	Upgrade Gradle lock

Identifying Java‑Only Patterns (e.g., Static Util Classes)

Static helper classes are the low‑hanging fruit. Scan for `public final class .* { private .*(); }` patterns. Those usually translate to Kotlin extension functions (`fun String.isEmail(): Boolean`) or a singleton `object`. The conversion reduces boilerplate and aligns with idiomatic Kotlin, cutting down on method count and improving readability.

Migration Strategy: The Strangler Fig Pattern

Setting Up Mixed‑Mode Compilation (Java + Kotlin)

Edit `build.gradle.kts` (yes, we’re already on Kotlin DSL) to enable the K2 compiler and mixed‑language builds:

// build.gradle.kts (Kotlin DSL) – Gradle 8.5
plugins {
    id("com.android.application") version "8.5.0"
    kotlin("android") version "2.0.0"
    kotlin("kapt") version "2.0.0"
}

// Enable K2 for faster compilation
kotlin {
    jvmToolchain(17)
    experimental {
        coroutines "enable"
        compilerOptions {
            freeCompilerArgs += listOf("-Xbackend-threads=4", "-Xuse-ir")
        }
    }
}

// Mixed Java–Kotlin source sets
android {
    sourceSets {
        getByName("main") {
            java.srcDirs("src/main/java")
            kotlin.srcDirs("src/main/kotlin")
        }
    }
}

Now Java and Kotlin coexist, and you can compile either without a full project sync.

Gradle Configuration for Incremental Migration

Gradle’s `incremental` flag can be turned on for Kotlin compilation:

androidComponents {
    beforeVariants { variant ->
        variant.enable = variant.name == "release" // keep debug fast
    }
}

// Force Kotlin to only recompile changed files
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
    kotlinOptions {
        incremental = true
        // K2 back‑end
        freeCompilerArgs += "-Xuse-k2"
    }
}

With this setup, each module you convert stays isolated, and CI pipelines only rebuild the changed parts.

Step‑by‑Step Technical Migration Process

Phase 1: Converting Data Models and POJOs

Start with plain old Java objects (POJOs). Open a class, click **Code → Convert Java File to Kotlin**, and accept the defaults. The converter will add `@JvmField` and `@JvmStatic` where needed, but you’ll usually replace those with Kotlin `val`/`var` and `data class` declarations.

// User.kt – Kotlin 2.0
// src/main/kotlin/com/example/models/User.kt
data class User(
    val id: String,
    val name: String,
    val email: String?,
    val createdAt: Instant = Instant.now()
)

Notice the nullable `email`. The compiler will now warn you wherever `user.email.length` is called without a safe‑call, catching NPEs before they ship.

Phase 2: Migrating Utility Classes to Extension Functions

Take a static helper like `StringUtils.isBlank(String)`. Convert it to:

// StringExtensions.kt
fun String?.isBlankOrNull(): Boolean = this == null || this.isBlank()

All callers can now use `someString.isBlankOrNull()`. The change is atomic: replace the import, delete the old Java class, and run the tests.

Phase 3: Handling Android Lifecycle Components

When you hit Activities, Fragments, or ViewModels, replace anonymous listeners with Kotlin **lambdas** and **coroutines**. For example, a typical RxJava subscription becomes:

// MyViewModel.kt
private val viewModelScope = CoroutineScope(Dispatchers.Main + SupervisorJob())

fun loadData() {
    viewModelScope.launch {
        try {
            val result = repository.fetchData()
            _state.value = result
        } catch (e: IOException) {
            _state.value = UIState.Error(e)
        }
    }
}

This eliminates memory‑leak‑prone disposables. If you’re still on the View system, read our guide on **Jetpack Compose Integration for View‑based apps** for a smooth bridge (internal link).

Phase 4: Test Coverage Strategy During Conversion

For each converted module, run `./gradlew testDebugUnitTest` and `connectedAndroidTest`. Add Kotlin‑specific assertions from `kotlin.test` and `Truth`. When a Java test fails after conversion, it’s often a platform‑type issue—use `@JvmName` or explicit nullability (`String!` → `String?`).

Critical Pitfalls: What the Docs Don’t Tell You

Handling “JavaClass” vs “KotlinClass” Reflection Issues

Reflection on a Kotlin `object` yields a `java.lang.Class` named `MySingleton$Companion`. If you rely on `Class.forName(“com.example.MySingleton”)`, you’ll hit a `ClassNotFoundException`. The fix is to reference the generated companion:

val kClass = Class.forName("com.example.MySingleton\$Companion")

Or, better yet, replace reflection with a Service‑Locator pattern using Dagger‑Hilt.

The De‑obfuscation Problem: ProGuard/R8 Rules Update

Mixing Java and Kotlin changes the generated bytecode names. After you convert a file, run:

./gradlew app:assembleRelease -Pandroid.experimental.r8.fullMode=true

Then, generate a fresh mapping file with `./gradlew app:printMapping`. Add entries for Kotlin synthetic accessors, e.g.:

# Kotlin synthetic accessor for property 'name' in data class User
-keepclassmembers class com.example.models.User {
    *** getName();
    *** setName(...);
}

If you forget this, crash logs for Kotlin code will appear as garbled symbols, making root‑cause analysis a nightmare.

Handling Platform Types and Implicit Nullability

Kotlin sees Java types like `String` as **platform types** (`String!`). The compiler won’t warn you, but at runtime you can still hit NPEs. To tame this, annotate the Java sources with `@Nullable` / `@NotNull` or adopt JSpecify (`@NonNull`, `@Nullable`). After annotation, the Kotlin compiler treats them as proper nullable or non‑null, surfacing errors earlier.

// JavaUtil.java
import org.jspecify.annotations.Nullable;

public class JavaUtil {
    public static @Nullable String fetch(Optional<String> opt) {
        return opt.orElse(null);
    }
}

Now Kotlin sees `fetch` returning `String?` and forces a safe‑call.

Performance Benchmarking: Java vs. Kotlin 2.0

APK Size Impact Analysis

We built two identical feature branches: one 100 % Java, one 70 % Kotlin after Phase 2. The Kotlin branch added **12 KB** of Kotlin stdlib (compressed) but shaved **38 KB** of generated bytecode by eliminating getters/setters. Net result: **‑26 KB** reduction in the final APK.

Metric	Java‑only	Kotlin‑70%
APK size (compressed)	23.4 MB	23.1 MB
Method count	61,800	57,200
Dex files	2 (multidex)	1 (single‑dex)

Cold Start Time Comparison

Using Android Studio’s **Profiler**, we measured cold start:

Build	Avg. Cold Start (ms)
Java‑only (Android 13)	820
Kotlin 2.0 (K2 enabled)	710

The improvement stems from fewer method references and faster bytecode verification thanks to the K2 front‑end.

Memory Footprint Profiling

Heap snapshots revealed a **4 % decrease** in retained objects after converting utilities to extension functions. Coroutines added a negligible overhead compared to RxJava threads, and the removal of static singletons freed up classloader memory.

**Pro tip:** Enable R8 **Full Mode** (`-Pandroid.experimental.r8.fullMode=true`) to let the optimizer strip unused Kotlin synthetic methods aggressively.

Case Study: Enterprise Migration at Scale

Our client, a fintech platform with 5 M daily active users, tackled a 2 M LOC monolith. The migration spanned 12 months using the **Strangler Fig** approach. Key lessons:

Lesson	Why it mattered
Convert data layer first	Null‑safety bugs dropped 42 %
Decommission Java singletons early	Method count fell below 64K, removed multidex
Adopt Hilt + Kotlin `object` for DI	Boilerplate cut by 30 %
Keep JSpecify annotations on legacy Java	Mixed‑mode null‑safety stayed consistent

The team reported a **30 % reduction** in overall LOC and a **40 % drop** in production NullPointerExceptions, echoing the 2023 Slack Engineering study.

Common Errors & Fixes

Error 1 – “Unresolved reference: coroutineScope”

**Symptom:** After converting a service to use `launch {}` the compiler flags `coroutineScope` as unknown.

**Cause:** The module’s `build.gradle.kts` is missing the `kotlinx-coroutines-android` dependency.

**Fix:**

// Add to dependencies block
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0")

Re‑sync Gradle and the error disappears.

Error 2 – “ClassCastException: com.example.User cannot be cast to java.lang.String”

**Symptom:** Runtime crash when a JSON parser, still written in Java, tries to cast a Kotlin `data class` to `String`.

**Cause:** The parser expects a Java bean with getter‑setter methods; Kotlin’s `data class` synthesizes `componentN` instead.

**Fix:** Add `@JvmField` or expose Java‑style accessors:

data class User(
    @JvmField val id: String,
    @JvmField var name: String
)

Or migrate the parser to **Moshi** or **Kotlinx Serialization**, which understand Kotlin metadata.

Error 3 – “Mapping file missing for class com.example.MyKotlinClass”

**Symptom:** Crash report from a beta build shows a mangled stack trace `a.b.c.d$1`.

**Cause:** R8 Full Mode generated a new obfuscation map after a Kotlin conversion, but the CI pipeline still uploads the old `mapping.txt`.

**Fix:** Update the CI step that publishes symbols:

./gradlew app:assembleRelease -Pandroid.experimental.r8.fullMode=true
cp app/build/outputs/mapping/release/mapping.txt ./ci/artifacts/

Make sure the new mapping is attached to the crash‑reporting service (Firebase Crashlytics, Sentry, etc.).

Error 4 – “Cannot find symbol: extension function isBlankOrNull”

**Symptom:** After converting a utility