Debug Annotation Processor Kapt


does anyone have experience with debugging custom annotation processors? I’m not able to figure out how to do it.
Based on this SO thread I started gradle using

./gradlew --no-daemon -Dorg.gradle.debug=true -Dkotlin.daemon.jvm.options="-Xdebug,-Xrunjdwp:transport=dt_socket\,address=5005\,server=y\,suspend=n" :clean assemble

Also it looks like I am able to connect to it using idea’s remote debug configuration.
The problem I have is that it does not seem to hit my breakpoint.

Any help is appreciated. I really don’t want to have to use print statements for debugging :wink:



By default all Kotlin tasks run in Kotlin Compile Daemon, which is a separate process.

This argument:


tells Kotlin to start a daemon process, which will listen on 5005 port for a debugger.

org.gradle.debug=true tells Gradle to start a process, which will listen on 5005 port for a debugger.

Two processes cannot listen on the same port, so you should specify a different port for Kotlin daemon.
Alternatively you can simply omit -Dorg.gradle.debug=true, since KAPT runs APs in Kotlin daemon.

If you’re using Kotlin 1.3.20, you can also add kapt.use.worker.api=true to Gradle properties, and debug Gradle process instead. Note that only with 1.3.20 kapt.use.worker.api runs KAPT in-process (before this option used Gradle Worker Processes by default).



hi @tsvetkov,
what is the difference between kapt.user.worker.api= true compared to ?
Previously, I only added, but when I added both of them, I got extremely high GC time. Or maybe I need to increase the max heap size for kotlin processes ?
I also noticed the task become: org.jetbrains.kotlin.gradle.internal.KaptWithoutKotlincTask
from org.jetbrains.kotlin.gradle.internal.KaptKotlincTask. Do you mind to explain what is the differences between those two ? Appreciate your help.



Hi @doniwinata03,

Gradle Worker API allows plugins to submit isolated (i.e. they don’t have access to Gradle model) units of work, that can be executed in parallel. Also Worker API allows (but not requires) plugin developers to use Worker daemon processes, which are managed by Gradle.

By default Kotlin runs the compiler and KAPT in Kotlin Compile Daemon.

KAPT runs in two stages:

  1. Stubs generation, which generates .java stub files from Kotlin source files.
  2. Actual annotation processing, which executes annotation processors on stubs and java sources.

kapt.use.worker.api=true does two things:

  1. It uses Worker API for the second stage (annotation processing), so (non stubs generating) KAPT tasks can run in parallel.
  2. Also it moves the second stage (annotation processing) out of Kotlin Compile Daemon (mostly to avoid affecting non-KAPT compilation). Before 1.3.20 annotation processing was run using Gradle Worker processes, but it lead to increased memory consumption (because a Worker process cannot be used concurrently, see Since 1.3.20 kapt.use.worker.api runs annotation processing in the main Gradle process. was added later. It simply uses Worker API for compileKotlin/compileKotlin2Js/compileKotlinCommon tasks, so these tasks can run in parallel. This mode does not use Worker processes, compilation is still performed in Kotlin Compile Daemon.
The name of the property might be a little confusing, I’ve chosen it to highlight the reason a user might want to enable it:

  • Without Worker API it was possible to execute tasks from different projects (one task per project) in parallel (via --parallel command line flag or by specifying org.gradle.parallel=true).
  • Only Worker API allows for parallel execution of independent tasks from the same project.

In all cases parallel execution may increase memory usage (because compiler’s threads don’t share any data). kapt.use.worker.api may increase memory usage in main Gradle process, may increase memory usage in Kotlin Compiler Daemon process.

By default Kotlin Daemon uses the same amount of memory as main Gradle process (which is controlled by org.gradle.jvmargs=-Xmx<MAX_HEAP_SIZE> project property). Kotlin Daemon’s heap size can be controlled by kotlin.daemon.jvm.options system property.

E.g. to set main Gradle process heap size to 768MB, and Kotlin Daemon heap size to 2GB, add the following to

org.gradle.jvmargs=-Xmx768m -Dkotlin.daemon.jvm.options=-Xmx2g

You can use the standard jvisualvm utility from your JDK installation to determine the optimal heap size.

1 Like