Gradle Kotlin "kapt"/"ksp" Failed - Fix Annotation Processing in CI

By Daniel Zoghalchali·Latchkey

A Kotlin annotation-processing task (kapt or ksp) failed. Common causes are the processor not declared on the right kapt/ksp configuration, a KSP plugin version mismatched to the Kotlin version, an actual processing error in your annotated code, or a kapt stub-generation OOM.

What this error means

The build fails at :kaptGenerateStubsKotlin/:kspKotlin with an annotation-processor error, error: [ksp] ..., a version-incompatibility message, or an OutOfMemoryError during kapt stub generation.

gradle output

> Task :app:kaptGenerateStubsKotlin FAILED
e: [ksp] com.example.MyProcessor: failed to process: ...
# or a version mismatch:
ksp-1.9.0-1.0.13 is too old for kotlin-1.9.24. Please upgrade ksp ...

Common causes

Processor not on the kapt/ksp configuration

Declaring the processor as a normal implementation instead of kapt(...)/ksp(...) means it never runs, and generated code is missing.

KSP/Kotlin version mismatch or kapt OOM

The KSP plugin version is tied to a specific Kotlin version; a mismatch fails the task. kapt stub generation is also memory-heavy and can OOM on small runners.

How to fix it

Declare the processor on the right configuration

Use the ksp(...)/kapt(...) configuration and a KSP version matched to your Kotlin version.

build.gradle.kts

plugins {
    kotlin("jvm") version "1.9.24"
    id("com.google.devtools.ksp") version "1.9.24-1.0.20"   // match Kotlin
}
dependencies {
    ksp("com.example:my-processor:1.4.0")
}

Give kapt more memory or prefer KSP

Raise the Kotlin/daemon heap, or migrate to KSP which is faster and lighter than kapt.

gradle.properties

# gradle.properties
org.gradle.jvmargs=-Xmx3g -XX:MaxMetaspaceSize=1g
kapt.use.worker.api=true

How to prevent it

Keep the KSP plugin version locked to the Kotlin version (<kotlin>-<ksp>).
Declare processors on ksp/kapt, never plain implementation.
Prefer KSP over kapt for speed and lower memory; size the daemon heap accordingly.

Frequently asked questions

What causes ""Execution failed for task ':kaptKotlin'" / KSP error"?

Declaring the processor as a normal implementation instead of kapt(...)/ksp(...) means it never runs, and generated code is missing.

How do I fix "Execution failed for task ':kaptKotlin'" / KSP error?

Use the ksp(...)/kapt(...) configuration and a KSP version matched to your Kotlin version.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.