Kotlin's new separate compilation scheme aligns multiplatform builds with the IDE
Public- 28 Sep, 2026

Kotlin Multiplatform's existing compilation approach works, but it can produce unexpected and hard-to-predict behavior. The core issue is a disagreement between the IDE and the compiler about how calls from common source sets to declarations in dependencies should be resolved. In Kotlin 2.5.0-Beta1, JetBrains introduced an optional "separate compilation" that aims to fix this: making compilation results consistent with IDE analysis and pointing more precisely to problematic calls from common source sets into library code. As a bonus, the scheme also enables incremental compilation for common source sets.
The problem stems from how a KMP module is structured. A module with common code typically has several source sets: a shared one (commonMain) and platform-specific ones (jvmMain for Kotlin/JVM). During compilation of a platform source set, code in jvmMain plus all related shared source sets is compiled against the platform artifacts of dependencies. This gives code in commonMain a chance to implicitly resolve to a jvmMain declaration in a dependency, which is exactly what IntelliJ IDEA does not allow. Because jvmMain declarations are not included in KLIB metadata, the IDE reports an "unresolved reference" error for such calls, while the compiler silently accepts them and the code builds without errors.

Turning on separate compilation makes the compiler behave more strictly, aligning its behavior with the IDE. The opt-in flag is added to gradle.properties as kotlin.kmp.separateCompilation=true, and the feature is disabled by default because it is Experimental. With the option enabled, code that previously compiled now fails: for example, a call to Foo from app/commonMain, when class Foo is declared only in lib/jvmMain, becomes a compilation error rather than an IDE-only warning. The fix is to establish an explicit connection using expect/actual: declare expect class Foo in lib/commonMain and mark the platform version as actual class Foo. The same rule applies to commonTest source sets, since tests "depend" on main code; commonTest compiled against jvmMain can no longer reach platform declarations without a matching expect in commonMain.
The scheme also resolves overload-selection mismatches. When several overloads exist across lib/commonMain and lib/jvmMain, the IDE and compiler currently pick different declarations. For example, with fun foo(x: Any) in commonMain and fun foo(x: String) in jvmMain, the IDE resolves foo("") to the common overload Any, but compilation chooses the more specific overload String, so "platform" is printed at runtime. Under separate compilation, the call resolves to the common declaration and "common" is printed, matching IDE behavior. A trickier failure appears when the error surfaces only in platform code: when actual classes add supertypes their expect counterparts lack, return-type inference can collapse to Any on the JVM and break a reference to .name, causing build failures only on the JVM.

With separate compilation, app/commonMain resolves calls only against declarations from eventsLib/commonMain, so the compiler infers the correct return type Event, and the JVM compilation finishes cleanly. JetBrains documents known issues that are still being fixed. Most importantly: for separate compilation to work correctly, library authors must publish metadata KLIBs. This is already the default behavior of the KMP Gradle plugin's publishing tasks, but the new scheme makes these KLIBs essential. Because the feature is Experimental, expect stricter compile-time checks and plan to adjust existing code accordingly.
