Kotlin K2 Compiler Migration: What Breaks and Why

Kotlin K2 compiler migration is the upgrade most teams put off until they couldn’t anymore — and now they’re dealing with the consequences. K2 became the default in Kotlin 2.0 (May 2024), it’s stable, it’s faster, and it’s also stricter. Code that compiled cleanly under K1 for years now produces type mismatch errors, smart cast failures, and annotation processor incompatibilities that nobody anticipated because nobody documented them clearly. JetBrains’ migration guide covers the happy path. This page covers what actually breaks — the specific patterns, the reasons behind them, and the concrete fixes.

TL;DR

• K2 compiler is the default in Kotlin 2.0+ and brings real build time improvements — typically 2x faster compilation on large projects
• K2 type inference is stricter than K1 in specific cases — code that relied on K1’s more permissive inference will fail to compile, often with confusing error messages
• Smart cast behavior changed in K2 — some smart casts that K1 allowed are rejected because K2 more accurately tracks mutability and control flow
• kapt is officially deprecated in K2 — it still works but KSP is the migration target, and some kapt-based processors have subtle behavioral changes under K2
• Third-party compiler plugins need explicit K2 compatibility — check every plugin before enabling K2, some fail silently rather than loudly
• The safest migration path is enabling K2 per-module with languageVersion = "2.0" and fixing errors incrementally, not flipping it project-wide at once

Kotlin K2 Compiler Migration: What Actually Changed Under the Hood

K2 is not K1 with bug fixes. It’s a ground-up rewrite of the Kotlin compiler frontend — the part responsible for parsing your code, resolving types, and deciding what’s valid. K1 was the original compiler that shipped with Kotlin 1.x. K2 uses a new intermediate representation (IR) throughout the entire pipeline, where K1 used IR only in the backend.

Why does this matter practically? Because K1’s type inference had edge cases where it was more permissive than the language specification required. Code worked because K1 made a generous assumption that happened to be correct. K2, following the spec more precisely, rejects the same code. It’s not that your code was always broken — it’s that K1 was silently covering for it.

// Kotlin — K1 compiled this, K2 rejects it with type mismatch
fun processItems(items: List) {
 for (item in items) {
 if (item is String) {
 // K1: smart cast worked even through this transformation
 val processed = item.uppercase() // item treated as String
 }
 }
}

// In K2, certain control flow patterns that K1 smart-cast through
// require explicit casting:
fun processItemsK2(items: List) {
 for (item in items) {
 if (item is String) {
 val asString = item as String // explicit cast required in some K2 scenarios
 val processed = asString.uppercase()
 }
 }
}

The frustrating part isn’t fixing the code — the fix is usually one line. It’s understanding why something that worked for two years suddenly doesn’t. Without that understanding, every new K2 error feels arbitrary rather than systematic.

How Much Faster Is K2 Build Time in Practice?

On large projects (100k+ lines), JetBrains reports 2x build time improvements, and real-world reports on Reddit and GitHub confirm this range — though results vary significantly by project structure. Projects with many inter-module dependencies and heavy use of inline functions tend to see the largest gains. Projects with lots of annotation processing see smaller gains because kapt/KSP time doesn’t scale with K2’s improvements. The build time argument is real and material — it’s worth the migration friction on any project where compilation speed matters.

Is K2 Compiler Stable for Production in June 2026?

Yes — K2 has been stable since Kotlin 2.0 and is the default in all 2.x releases. The question isn’t stability of the compiler itself, it’s compatibility of your specific dependency and plugin ecosystem. K2 is production-ready; whether your particular combination of annotation processors, compiler plugins, and third-party libraries is K2-ready depends on each of them individually. Check before you enable, don’t assume.

K2 Type Inference Breaking Changes: The Code That Stops Compiling

Type inference changes are the most common source of K2 migration errors, and they come in two flavors: cases where K2 correctly rejects code that K1 incorrectly accepted, and cases where K2’s inference algorithm takes a different path than K1’s and arrives at a different type for an expression.

The second category is especially disorienting. The code isn’t wrong by the language spec — both K1 and K2 are making valid inferences — but K2’s inferred type doesn’t match what you were relying on. You get a type mismatch error and the compiler is technically correct even though the code was working fine yesterday.

// Kotlin — type inference difference between K1 and K2
// K1 inferred the lambda parameter type from context more aggressively

val result = listOf(1, 2, 3).fold(mutableListOf()) { acc, item ->
 acc.apply { add(item * 2) }
}
// K1: inferred result as MutableList
// K2: may infer as List depending on the exact expression shape
// Fix: explicit type annotation
val result: MutableList = listOf(1, 2, 3).fold(mutableListOf()) { acc, item ->
 acc.apply { add(item * 2) }
}

The fix is always the same: add an explicit type annotation. K2 respects explicit types — it only diverges when inferring implicitly. The debugging process is the slow part: understanding which inference the compiler is making and why it differs from K1. The compiler error message often points at the wrong line because the actual inference decision happens earlier in the expression.

Kotlin K2 Type Mismatch Error: Where to Look First

When K2 gives you a type mismatch that K1 didn’t, look at the outermost expression first, not the line the error points to. K2 errors in type inference chains often point to the final usage of a value, when the real issue is the inferred type of an intermediate expression several lines earlier. Add explicit type annotations starting from where the value is created, not where it’s used — this narrows the inference chain and usually surfaces the actual divergence point quickly.

Does K2 Change How Generic Type Parameters Are Inferred?

Yes, in specific cases involving variance and bounded type parameters. K2 is more careful about when it applies covariant or contravariant inference, which means some generic function calls that K1 resolved without explicit type arguments now require them in K2. The pattern looks like this: a call to a generic function works fine without type arguments in K1, fails with “type inference failed” in K2, and is fixed by adding the type argument explicitly. This is one of the most common K2 migration issues reported on YouTrack and Reddit r/Kotlin, and the fix is consistently the same — make the type argument explicit.

kapt vs KSP in K2: Why Annotation Processing Changed

kapt — the Kotlin Annotation Processing Tool — works by generating Java stubs from your Kotlin code and running Java annotation processors against those stubs. It was never pretty, but it worked. In K2, kapt is officially deprecated. It still functions, but it runs in K1 compatibility mode inside K2, which means you get the annotation processing behavior but not the build time improvements K2 would otherwise provide.

KSP (Kotlin Symbol Processing) is the replacement. It processes Kotlin symbols directly without stub generation, plays well with K2’s IR pipeline, and is typically 2x faster than kapt for the same workload. The migration catch: not all annotation processors have KSP implementations yet, and KSP 1.x had some behavioral differences from kapt that KSP 2.0 (targeting K2) is still ironing out.

// Kotlin Gradle — migrating from kapt to KSP in build.gradle.kts
plugins {
 kotlin("jvm") version "2.0.0"
 // Remove: id("kotlin-kapt")
 id("com.google.devtools.ksp") version "2.0.0-1.0.21" // KSP plugin
}

dependencies {
 // Remove: kapt("com.example:annotation-processor:1.0")
 ksp("com.example:annotation-processor-ksp:1.0") // KSP variant

 // Room example — Room has KSP support since 2.4
 // kapt("androidx.room:room-compiler:2.6.0") // old
 ksp("androidx.room:room-compiler:2.6.0") // new
}

Before switching, check whether your annotation processors have KSP variants. Room, Hilt, Dagger, Moshi, and most major Android libraries support KSP now. Smaller or older libraries may still be kapt-only — in that case, you can run kapt in K2 compatibility mode as a temporary measure while waiting for KSP support upstream.

kapt K2 Compatibility: What “Deprecated” Actually Means Right Now

Deprecated in Kotlin terms means: it still works, JetBrains still fixes critical bugs, but new features won’t land there and it will eventually be removed. For K2 specifically, kapt runs via a compatibility shim that adds overhead. You won’t get the full K2 build time benefit with kapt active — the stub generation step doesn’t parallelize with K2’s pipeline the way KSP does. If you have a mix of processors — some with KSP support, some kapt-only — run KSP for the ones that support it and kapt for the rest. Gradle supports both in the same project.

KSP K2 Migration: What Changes in Generated Code

In most cases, nothing visible — the generated code is semantically identical. The differences that do appear are in edge cases around visibility modifiers, internal class generation, and how certain Kotlin-specific constructs are represented. If you have code that depends on the exact structure of kapt-generated classes (inspecting them reflectively, or relying on specific naming patterns), audit those dependencies before migrating. For the vast majority of common processors like Room and Hilt, switching from kapt to KSP produces identical runtime behavior.

K2 Smart Cast Changes: When the Compiler Stopped Trusting You

Smart casts are one of Kotlin’s best features — the compiler tracks control flow and automatically narrows a type after a null check or type check, so you don’t have to cast manually. K2 changed smart cast analysis in ways that are technically more correct but feel more restrictive if you were relying on K1’s more generous behavior.

The core change: K2 tracks mutability more precisely. If a variable could theoretically be modified between the check and the use — even in cases where you know it won’t be — K2 refuses the smart cast. K1 was more willing to assume the variable stayed stable. K2 demands proof.

// Kotlin — smart cast failure in K2 that K1 allowed
class UserService {
 var currentUser: User? = null // var, not val — K2 sees mutation risk

 fun displayName(): String {
 if (currentUser != null) {
 // K1: smart cast worked here — currentUser treated as User
 return currentUser.name // K2: error — currentUser could change
 }
 return "Guest"
 }

 // K2-compatible fix: local val copy before the check
 fun displayNameK2(): String {
 val user = currentUser // capture in local val — immutable after capture
 if (user != null) {
 return user.name // K2 smart cast works on the local val
 }
 return "Guest"
 }
}

The fix is always “capture in a local val.” It’s a one-line change that makes the intent explicit and satisfies K2’s stricter flow analysis. Once you understand the pattern, it becomes mechanical — but before you understand it, every smart cast failure looks like a random compiler complaint.

Smart Cast Impossible After K2 Migration: The Most Common Cases

Three patterns account for most K2 smart cast failures: class properties that are var (K2 correctly identifies these as mutable and won’t smart cast through them), properties delegated to custom delegates where K2 can’t prove the getter is stable, and open properties in non-final classes where an override could change the value. In all three cases, the local val capture pattern fixes the issue. For delegated properties specifically, if the delegate is deterministic and you control it, you can also implement the ReadOnlyProperty interface explicitly to help K2 understand the stability guarantee.

Does K2 Add Any New Smart Cast Capabilities?

Yes — K2’s more precise flow analysis enables some smart casts that K1 couldn’t do. Particularly around sealed class hierarchies in when expressions and null checks in complex boolean conditions, K2 is smarter than K1. So the experience is mixed: some K1 smart casts that you relied on are now rejected, and some patterns that required explicit casts in K1 now work automatically in K2. The net result is more correct behavior overall, even if the migration requires fixing the cases where K1 was being too lenient.

Kotlin K2 Migration Checklist: What to Check Before Enabling

Don’t enable K2 project-wide on day one. Enable it module by module, starting with modules that have the fewest dependencies and annotation processors. Fix errors in that module, verify the build and tests, then move to the next module. This limits the blast radius of any individual issue and gives you a clear picture of which modules are K2-ready and which need more work.

Before enabling K2 in any module, audit three things explicitly.

Compiler plugins. List every kotlinOptions or compilerOptions entry in your Gradle files. For each compiler plugin, check the plugin’s GitHub or changelog for explicit K2 compatibility statements. A plugin that hasn’t been updated since 2023 is a yellow flag — test it in isolation before assuming it works.

Annotation processors. Inventory all kapt usages. For each processor, check whether a KSP variant exists and is stable. Don’t migrate processor-by-processor mid-project — decide upfront which ones you’re migrating and do them together, since mixing kapt and KSP in complex ways can produce subtle ordering issues in generated code.

IDE plugin versions. The Kotlin IDE plugin in IntelliJ IDEA and Android Studio needs to match or exceed the Kotlin language version you’re using. Running K2 language features with an older IDE plugin produces misleading red squiggles and false positive errors that don’t reflect actual compilation outcome. Update the IDE plugin first, then enable K2.

// Kotlin Gradle — enabling K2 per-module safely (build.gradle.kts)
kotlin {
 compilerOptions {
 languageVersion.set(KotlinVersion.KOTLIN_2_0) // explicit K2 opt-in
 apiVersion.set(KotlinVersion.KOTLIN_2_0)
 }
}

// Or with the older syntax:
tasks.withType {
 kotlinOptions {
 languageVersion = "2.0"
 apiVersion = "2.0"
 }
}

// Check that K2 is active with:
// ./gradlew :your-module:compileKotlin --info | grep "Using K2"

The --info grep at the bottom is genuinely useful — it confirms K2 is actually active rather than silently falling back to K1 compatibility mode because of a plugin conflict. More than one team has spent a day “migrating to K2” while Gradle was quietly running K1 the entire time because an incompatible plugin forced the fallback.

FAQ: Kotlin K2 Compiler Migration

What is the Kotlin K2 compiler and why should I migrate?

K2 is a ground-up rewrite of the Kotlin compiler frontend, stable since Kotlin 2.0 and the default in all 2.x releases. The primary reason to migrate is build time — K2 is typically 2x faster than K1 on large projects. It also enables new language features only available on K2 and is the only supported path forward as K1 is being phased out. Migration friction is real but manageable if done module by module.

How do I enable the K2 compiler in my Kotlin project?

Set languageVersion = "2.0" (or higher) in your module’s compilerOptions in Gradle. For a gradual migration, do this per module rather than project-wide. Verify K2 is actually active with ./gradlew :module:compileKotlin --info | grep "Using K2" — some plugin incompatibilities cause silent fallback to K1 without an error.

Why does my code fail to compile after enabling K2?

Most K2 compilation failures fall into three categories: type inference divergence where K2 infers a different type than K1 for an ambiguous expression (fix with explicit type annotations), smart cast rejections where K2 won’t smart cast through mutable properties (fix with local val capture), and annotation processor incompatibilities where a kapt plugin behaves differently or fails (check for KSP migration or K2 compatibility updates).

Is kapt still supported in K2?

Yes, but it’s deprecated. kapt runs in a K1 compatibility mode inside K2 — it still works but you won’t get the full build time benefits K2 offers, because kapt’s stub generation step doesn’t parallelize with K2’s pipeline. KSP is the migration target. For processors that don’t have KSP support yet, running kapt in compatibility mode is a valid interim approach.

What is the difference between kapt and KSP for K2?

kapt generates Java stubs from Kotlin code and runs Java annotation processors — it’s a compatibility shim that was never designed for K2. KSP processes Kotlin symbols directly, integrates cleanly with K2’s IR pipeline, and is typically 2x faster for annotation processing. KSP is the official replacement and most major libraries (Room, Hilt, Dagger) now have KSP implementations. kapt will continue working but won’t receive new features.

Why did my smart cast stop working after K2 migration?

K2 tracks mutability more precisely than K1. If the variable being smart cast is a var property, an open property, or a delegated property where K2 can’t prove the getter is stable, K2 rejects the smart cast even if you know the value won’t change. The fix is capturing the value in a local val before the null check — this gives K2 an immutable reference it can safely smart cast through.

Do third-party compiler plugins work with K2?

Only if they’ve been explicitly updated for K2 compatibility. Compiler plugins that target K1’s internal APIs need to be rewritten for K2’s different internal structure — it’s not a configuration change, it’s a code change by the plugin author. Check each plugin’s GitHub or changelog for explicit K2 support statements. Plugins without K2 support may fail loudly (build error) or silently (fall back to K1 mode) — both outcomes are better than a plugin that “works” but produces wrong output.

What is the safest way to migrate a large project to K2?

Enable K2 one module at a time, starting with leaf modules that have the fewest dependencies. Fix all compilation errors in each module before moving to the next. Audit compiler plugins and annotation processors before starting — incompatible ones will block migration of any module that uses them. Keep K1 as the fallback for modules where migration blockers exist, and migrate those modules after their dependencies (plugins, processors) receive K2 updates.