Kotlin Gradle Plugin Failures: KAPT vs KSP Traps, Multiplatform SourceSet Issues and Build Cache Problems

You merged sourceSets, the JVM target compiles clean, Android runs fine — and then the iOS framework build crashes with “unresolved reference” on symbols that clearly exist in commonMain. No helpful stack trace. No documentation warning. Just a broken Xcode build and a compiler that seems to be lying to you.

Kotlin Multiplatform’s sourceSet model is a directed graph, not a flat inheritance tree. Visibility propagates along declared dependency edges — and when those edges are reconfigured through dependsOn changes or plugin-managed hierarchy modifications, the compiler’s view of which symbols are accessible from which target changes silently.

This specific failure sits at the intersection of KMP’s dependency resolution model, Gradle’s incremental build cache, and the way Xcode consumes generated frameworks. The edge cases around iOS target visibility after sourceSet configuration changes are largely undocumented, community-discovered, and frequently misdiagnosed as Xcode issues when they are actually Gradle problems.

// build.gradle.kts
kotlin {
 sourceSets {
 // Plugin X silently adds dependsOn here during configuration phase,
 // breaking the iosMain → commonMain visibility edge
 val iosMain by getting {
 dependencies { implementation(project(":shared-utils")) }
 }
 }
}

// After plugin update: iosArm64Main no longer sees commonMain symbols.
// JVM compiles fine. iOS framework build: "Unresolved reference: MySharedClass"

kotlin {
 sourceSets {
 val iosMain by getting {
 dependsOn(commonMain.get()) // explicit, not implicit
 dependencies { implementation(project(":shared-utils")) }
 }
 }
}

A dependency declared in commonMain is supposed to propagate to all targets. But when the dependency is a multiplatform library with its own sourceSet hierarchy, resolution depends on the artifact metadata format. If the library publishes iosArm64 metadata but not iosSimulatorArm64, the iOS Simulator target resolves nothing and the symbols disappear from the framework. The JVM and Android targets compile fine because they consume JVM artifacts, not platform-specific metadata.

# Check what artifacts a library actually publishes
./gradlew dependencies --configuration iosSimulatorArm64MainImplementation

# If the library is missing iosSimulatorArm64 artifacts, you'll see:
# > Could not resolve com.example:some-lib:1.0.0
# No matching variant of com.example:some-lib:1.0.0 was found.

The expect/actual matching algorithm changed in Kotlin 1.9.x and again in the 2.x series. After a plugin update, previously valid expect/actual pairs fail to match because the compiler’s signature comparison now includes annotations or default parameter handling that wasn’t checked before. The error message says “actual declaration has no corresponding expect declaration” — technically accurate but completely unhelpful for locating what changed.

// commonMain
expect class PlatformDate(@Suppress("UNUSED") millis: Long)

// iosMain — compiled fine before Kotlin 2.x, fails after:
// "actual declaration has no corresponding expect declaration"
actual class PlatformDate(millis: Long) { ... }

// Fix: mirror the annotation on the actual declaration
actual class PlatformDate(@Suppress("UNUSED") millis: Long) { ... }

After ./gradlew clean, the processor-generated classes disappear from the compile classpath even though the annotation processor ran successfully. The build log shows processor execution, the generated files exist on disk, but the compiler reports “unresolved reference” on the very classes that were just generated.

This happens because KAPT runs as a separate Gradle task that outputs to a directory outside the standard source compilation classpath by default in multiplatform setups. When the project has multiple targets, the classpath wiring between KAPT output and the main compilation task depends on which target’s compilation task runs first. After a clean, task ordering changes, and the KAPT-generated sources directory is not registered on the classpath before the compiler task starts. It is a task dependency graph problem disguised as an annotation processor failure.

> Task :kaptGenerateStubsKotlin SUCCESS
> Task :kaptKotlin SUCCESS
> Task :compileKotlin FAILED

e: /src/main/kotlin/MyService.kt:12:5
 error: unresolved reference: MyRepoImpl

// Generated file EXISTS on disk:
// build/generated/source/kapt/main/com/example/MyRepoImpl.java
// But it is NOT on the compile classpath for this target.

// build.gradle.kts
kotlin {
 sourceSets {
 val main by getting {
 kotlin.srcDir("build/generated/source/kapt/main")
 }
 }
}

// Or, declare the task dependency explicitly:
tasks.named("compileKotlin") {
 dependsOn("kaptKotlin")
}

KAPT processes annotations by converting Kotlin bytecode to Java stubs. Inline functions do not survive this conversion intact — they get mangled because inlining is a compiler-level operation that KAPT’s stub generation phase does not reproduce correctly. The error messages are typically ClassNotFoundException on the stub class or a generic “error while processing” message with a stack trace pointing into KAPT internals, not your code.

Annotated inline functions that use reified type parameters are especially problematic. KAPT generates a stub that erases the type parameter, producing a different method signature than what the annotation processor expects to find.

@MyAnnotation
inline fun reified T> resolve(): T {
 return container.get(T::class)
}

// KAPT stub erases T → generates: Object resolve()
// Processor expects: T resolve() with reified metadata
// Result: ClassNotFoundException or silent stub mismatch

Incremental KAPT tracks which source files changed and re-runs only the relevant processors. The tracking mechanism uses file modification timestamps and a state file stored in the build directory. If any build step modifies the KAPT state file — including certain Gradle daemon restarts and plugin version changes — the incremental state becomes inconsistent. The processor runs but writes output to a stale location, or skips output entirely because the state file claims the target class is already up to date.

# Delete KAPT incremental state, not just the build output
rm -rf build/tmp/kapt3
rm -rf build/generated/source/kapt
./gradlew kaptKotlin

KSP processes sealed classes through its KSClassDeclaration API, which exposes sealed subclasses via getSealedSubclasses(). This call only returns subclasses declared in the same file or in files that KSP has already processed in the current build round. Sealed hierarchies split across multiple files — valid Kotlin since 1.5 — cause KSP to see an incomplete hierarchy during processing. Processors that generate exhaustive when-expression wrappers or registry classes based on sealed subclasses produce incomplete output without any error or warning from KSP.

// Result.kt
sealed class Result

// Success.kt — separate file, KSP may miss this in round 1
class Success(val data: String) : Result()

// Error.kt
class Error(val message: String) : Result()

// KSP-generated registry may only contain Success,
// missing Error entirely — no compilation error, silent bug.

Value classes compile to a box type and a specialized unboxed representation. KAPT sees only the box type when generating stubs. A processor that annotates a value class generates code based on the box representation, missing the unboxed call sites that appear in actual usage. KSP has better value class support but still does not expose the unboxed representation through its API — processors see the value class as a wrapper, not as the underlying type, producing generated code that compiles but does not match the runtime method signatures.

When a coroutines-annotated function is processed by KAPT, the annotation processing happens on the Java stub representation. The stub for a function that uses suspend does not include the coroutine continuation parameter that the Kotlin compiler adds during suspension point transformation. Any annotation processor that generates code based on the method signature — particularly Room or Hilt — generates code against the stub signature, not the actual compiled signature, producing a method-not-found error at runtime that does not appear until the generated code executes a coroutine call path.

// Kotlin source
@Query("SELECT * FROM users")
suspend fun getUsers(): List<User>

// KAPT stub (Java representation — continuation stripped)
// List<User> getUsers()

// Actual compiled Kotlin bytecode (what Room needs to call)
// Object getUsers(Continuation<? super List<User>> continuation)

// Room generates code targeting the stub → MethodNotFoundException at runtime

KAPT writes generated sources to build/generated/source/kapt/<variant>/. KSP writes to build/generated/ksp/<target>/<sourceSet>/. Projects migrating from KAPT to KSP need to update any hardcoded references to generated source directories in their build scripts, IDE configurations, and CI pipelines. More critically, the generated package structure can differ between processors because KAPT processors targeting Java often generate classes in the root package, while KSP processors following Kotlin conventions generate into the annotated class’s package.

// Before (KAPT)
android {
 sourceSets["main"].java.srcDirs(
 "build/generated/source/kapt/debug"
 )
}

// After (KSP)
android {
 sourceSets["main"].java.srcDirs(
 "build/generated/ksp/debug/kotlin"
 )
}

The Kotlin Gradle Plugin embeds a specific version of the Kotlin compiler. Updating the plugin updates the embedded compiler. If the compiler version changes how it handles certain language constructs — particularly around type inference improvements or IR backend changes — code that compiled before will fail after the update even though the JVM target version has not changed. The failure typically shows up as a type mismatch or overload resolution ambiguity.

# Print the embedded Kotlin compiler version
./gradlew kotlinVersion

# Or check in the Gradle build scan — look for:
# "org.jetbrains.kotlin:kotlin-compiler-embeddable:X.Y.Z"

The IR backend maintains its own incremental compilation state separate from the classic backend’s state files. Switching between backends — or updating a plugin that changes which backend is used — leaves stale state files that the new backend either misreads or ignores. The build then either recompiles everything (best case) or compiles with a corrupted incremental state that produces incorrect output (worse, harder to detect).

rm -rf build/kotlin
./gradlew --rerun-tasks compileKotlin

Kotlin DSL buildscripts are compiled against the Gradle API classpath at configuration time. When a plugin adds its own classes to the buildscript classpath, the Kotlin DSL compiler resolves types differently than the Groovy evaluator. A plugin that works perfectly in a Groovy build file can produce “unresolved reference” errors in the equivalent Kotlin DSL configuration because the plugin’s classes are not on the Kotlin DSL compilation classpath at the right phase.

// Groovy — works
apply plugin: 'com.example.myplugin'
myPlugin { option = "value" }

// Kotlin DSL — fails: "Unresolved reference: myPlugin"
apply(plugin = "com.example.myplugin")
configure<MyPluginExtension> { option = "value" }

// Fix: add plugin to buildscript classpath explicitly
buildscript {
 dependencies {
 classpath("com.example:myplugin:1.0.0")
 }
}

A crossinline lambda inside an inline function cannot be a suspend lambda because crossinline prohibits non-local returns, and the coroutine state machine transformation requires the ability to restructure control flow in ways that conflict with crossinline‘s constraints. The compiler error “suspension functions can only be called within coroutine body” is accurate but does not explain that the root cause is the crossinline modifier, not the calling context.

inline fun withContext(crossinline block: suspend () -> Unit) {
 runBlocking { block() }
 // ↑ Compiler error: "Suspension functions can only be called within coroutine body"
 // Real cause: crossinline + suspend are incompatible modifiers
}

// Fix: remove crossinline, allow non-local returns
inline fun withContext(block: suspend () -> Unit) {
 runBlocking { block() }
}

The flow { } builder uses an internal SafeFlow implementation that wraps emissions in exception handling. On Android, the R8/D8 bytecode transformation pipeline can remove or inline parts of this wrapping in ways that break the exception contract. The runtime exception — typically a FlowCollector cancellation leak — appears in production under specific concurrency conditions that do not reproduce in debug builds because R8 operates only in release mode.

Coroutines in commonMain compile to different underlying implementations depending on the target. JVM uses thread-based coroutine dispatchers; JS uses a single-threaded event loop model. Code that assumes thread-safe coroutine behavior in commonMain — particularly anything using Mutex or Channel with structured concurrency — will behave differently on JS where blocking operations simply do not exist. The JS target compiles successfully but produces runtime behavior that diverges from the JVM implementation in subtle, hard-to-test ways.

Suspend lambdas in commonMain compile to different representations on JVM (continuation-passing style) and on Kotlin/Native (native coroutine primitives). A suspend lambda that captures a mutable variable from the enclosing scope compiles on JVM because the JVM’s garbage collector handles the captured reference lifecycle. On Kotlin/Native, captured mutable references require explicit memory management annotations in certain coroutine contexts — their absence produces a compile-time error that only manifests on the iOS target.

// commonMain — compiles on JVM, fails on iosArm64
var counter = 0
val lambda: suspend () -> Unit = {
 counter++ // mutable capture — illegal in Kotlin/Native coroutine context
}

// Fix: make the captured reference immutable or use AtomicInt
val counter = AtomicInt(0)
val lambda: suspend () -> Unit = { counter.incrementAndGet() }

The flow { } builder enforces a single-collector constraint through an internal flag on the FlowCollector. On Kotlin/Native, the threading model means this flag check runs on a different thread than the flag setter in certain Dispatcher configurations. The result is an IllegalStateException with the message “Flow invariant is violated” — accurate for the symptom but pointing nowhere toward the actual cause: a Dispatcher mismatch between the flow producer and consumer that is legal on JVM but illegal on native’s threading model.

// Problematic: Dispatchers.Default mixes threads on native
val myFlow = flow {
 emit(fetchData())
}.flowOn(Dispatchers.Default)

// Fix: collect on the same dispatcher that produces
scope.launch(Dispatchers.Main) {
 myFlow
 .flowOn(Dispatchers.Main)
 .collect { ... }
}

The serialization plugin processes class visibility before generating serializer code. An internal sealed class in commonMain is internal to the module, but the generated serializer companion object needs to be accessible from the platform-specific modules that consume the serialized data. The plugin generates the companion with the same visibility as the sealed class, making it inaccessible from the consuming platform module. The build succeeds; serialization fails at runtime with a “Serializer not found” exception that points at the class rather than the visibility problem.

// Fails at runtime — serializer generated as internal
@Serializable
internal sealed class ApiResponse

// Fix: make the sealed class public,
// or use @PublishedApi if internal access is required
@Serializable
sealed class ApiResponse

// Or suppress visibility propagation explicitly:
@Serializable
@OptIn(ExperimentalSerializationApi::class)
internal sealed class ApiResponse {
 companion object : KSerializer<ApiResponse> { ... }
}

Enum classes in commonMain require the serialization plugin to generate a serializer that maps enum constants to their string or ordinal representations. When the enum is declared in a file that is also processed by KAPT or KSP, the compiler plugin execution order determines whether the serialization plugin sees the original enum declaration or KAPT’s transformed version. If KAPT runs first and modifies the class metadata, the serialization plugin may not recognize the class as an enum and silently skips serializer generation.

The serialization plugin generates platform-specific serializer implementations. The JSON format serializer for JVM uses reflection-based fallbacks for certain type scenarios; the native (iOS) serializer cannot use reflection and requires fully code-generated paths. When a type uses a feature that the code generation path does not support — certain generic type combinations, delegated properties, or companion object customizations — the JVM serializer works via reflection fallback while the iOS serializer fails at compile time with a generation error. This asymmetry makes serialization bugs iOS-only, discovered late in the development cycle.

@Serializable
data class Wrapper<T : Any>(val value: T)

// JVM: works via reflection fallback
// iOS: compile error — "Serializer for type T cannot be generated"

// Fix: provide a concrete serializer at the call site
@Serializable
data class StringWrapper(val value: String)

// Or use @Contextual for types that need runtime lookup
@Serializable
data class Wrapper<T : Any>(@Contextual val value: T)

When you add a new dependsOn relationship between sourceSets — or remove one — the incremental compilation state for both sourceSets becomes invalid. Gradle does not detect this structural change as a reason to invalidate the compilation cache. The compiler then operates with an incremental state that was built from a different sourceSet graph than is currently configured, producing stale symbol resolution that passes or fails inconsistently depending on which files were last modified.

# Remove Kotlin incremental compilation state for all targets
find build -name "*.kotlin_module" -delete
find build -name "last-build.bin" -delete
./gradlew clean build

The Kotlin/JVM, Kotlin/JS, and Kotlin/Android backends compile to different intermediate representations and have backend-specific compiler checks. Code that uses JVM-specific APIs directly — even through expect/actual — may compile for JVM while the JS or Android backend lacks an equivalent actual declaration. Incremental compilation makes this worse: if the JVM target compiles first and caches its output, a subsequent JS build may skip recompilation of unchanged files and fail only on recently modified files, making the failure seem unrelated to the actual source of the problem.

Gradle’s build cache uses task input hashing to determine cache hits. Plugin JARs are included in the task input hash, so updating a plugin should theoretically invalidate the cache. In practice, the Kotlin Gradle Plugin’s task inputs do not always include all compiler plugin JARs in the hash. After an update, cached task outputs from the previous plugin version get reused, producing binaries compiled with the old compiler against new API expectations.

# Invalidate local cache
./gradlew clean --rerun-tasks

# Invalidate local + remote — disable local cache temporarily
./gradlew build 
 -Dorg.gradle.caching=false 
 --rerun-tasks

# Or add a unique build parameter to change the task input hash
./gradlew build -PcacheBuster=$(date +%s)

Android target compilation resolves commonMain symbols through Gradle’s dependency graph at compile time. iOS compilation resolves them during Kotlin/Native framework generation, which happens as a separate Gradle task with its own classpath. If the framework generation task does not have the correct dependencies on the tasks that compile commonMain, it runs with a stale or empty classpath. The Android build succeeds because it resolves at compile time; the iOS framework build fails because it resolves at framework generation time with a different task graph.

# Print task dependency graph for iOS framework generation
./gradlew linkDebugFrameworkIosArm64 --dry-run

# Look for: compileKotlinIosArm64 appearing BEFORE linkDebugFrameworkIosArm64
# If it's missing, add an explicit dependency:
tasks.named("linkDebugFrameworkIosArm64") {
 dependsOn("compileKotlinIosArm64")
}

Resources declared in commonMain/resources are not automatically included in the Kotlin/Native framework. The framework compilation process compiles Kotlin sources and generates headers — resource bundling is a separate, manually configured step. Developers who expect resource access patterns from Android (where the Android Gradle Plugin handles resource merging) find that the same approach produces a framework with missing assets that fails at runtime, not at compile time, making the missing resources hard to detect during development.

After a Kotlin Gradle Plugin update, the compiler’s rules for what constitutes a valid actual declaration for a given expect may change. The iOS target uses Kotlin/Native, which has stricter rules around nullability, platform type handling, and generic variance than the JVM target. An actual declaration that was previously accepted by the iOS compiler may be rejected after the update due to stricter checking, while the same actual on JVM continues to compile. The error appears only in the iOS build, creating a situation where the shared codebase compiles on one platform but not another despite no source changes.

KtLint’s formatter handles lambda formatting through a rule that inspects the lambda’s position in the AST. Suspend lambdas have a different AST node structure than regular lambdas — the suspend keyword introduces an additional node level that KtLint’s lambda-formatting rule does not account for. The formatter either skips the lambda entirely or applies single-argument lambda formatting rules incorrectly, producing output that re-triggers the formatter on the next run — an infinite formatting loop if you have formatting as a pre-commit hook.

Detekt’s complexity metrics — particularly CyclomaticComplexity and CognitiveComplexity — calculate function complexity based on control flow graph analysis. Inline functions get analyzed independently, without accounting for the fact that their complexity distributes to call sites. A utility inline function with a few branches gets flagged as too complex even though each call site only experiences a linear subset of that complexity. Suppressing the finding requires per-function annotations, which pollutes the source with noise that the CI pipeline then treats as suppression debt.

@Suppress("CyclomaticComplexMethod")
inline fun evaluateConditions(block: () -> Boolean): Boolean {
 // Complexity is distributed to call sites at compile time
 ...
}

Multiline strings in Kotlin DSL build files use trimIndent() or trimMargin() to handle indentation. KtLint’s string template rules apply indentation normalization that conflicts with trimIndent‘s expected input format. After KtLint formatting, the trimIndent call receives differently indented content and produces incorrect output at runtime — a build configuration that silently uses wrong values rather than failing with an error.

val query = // ktlint-disable
 """
 SELECT *
 FROM users
 WHERE active = true
 """.trimIndent()
// ktlint-enable