KaptExecution en Kotlin : ce qui se cache derrière l'erreur Gradle

Introduction : pourquoi KaptExecution casse la build et comment y remédier

Si vous avez déjà rencontré l'erreur A failure occurred while executing org.jetbrains.kotlin.gradle.internal.KaptExecution, vous savez à quel point cela peut être déstabilisant. La build échoue, Gradle affiche du texte rouge, et les logs contiennent des stacktraces incompréhensibles. Sur Stack Overflow, cette question a recueilli des milliers de vues, mais la plupart des réponses se résument à "essaye de vider le cache". Nous allons aller plus loin.

Dans cet article, nous ne nous contenterons pas de donner des solutions toutes faites. Nous allons regarder sous le capot du mécanisme Kapt (Kotlin Annotation Processing Tool) et comprendre ce qui se passe exactement lorsque Gradle exécute KaptExecution. Vous apprendrez comment fonctionne la génération de code, où se cachent les erreurs typiques et comment les éviter. Et surtout, vous obtiendrez des exemples fonctionnels en Kotlin que vous pourrez appliquer immédiatement dans votre projet.

Ceci est un contenu éducatif pour pythonlib.ru, adapté aux développeurs qui veulent non pas copier des commandes, mais comprendre ce qui se passe à l'intérieur du builder.

Qu'est-ce que KaptExecution et à quoi sert-il

Kapt est un plugin pour Kotlin qui permet d'utiliser des annotation processors compatibles Java (par exemple, Dagger, Room, Glide, Moshi) dans des projets Kotlin. Lorsque vous écrivez une annotation @Inject ou @Entity, le compilateur génère du code supplémentaire (classes, factories, DAO).

À l'intérieur de Gradle, Kapt fonctionne comme une tâche distincte. Lorsque vous lancez la build, Gradle appelle KaptExecution — c'est la commande qui exécute le compilateur Kotlin avec le traitement des annotations activé. Si quelque chose se passe mal à cette étape (par exemple, le processor a levé une exception ou la mémoire est insuffisante), vous voyez cette fameuse erreur.

À quoi ressemble KaptExecution dans Gradle

Dans le fichier build.gradle.kts (ou build.gradle), Kapt se connecte ainsi :

plugins {\n    kotlin("kapt") version "1.9.0"\n}\n\ndependencies {\n    kapt("com.google.dagger:dagger-compiler:2.48")\n}\n

Lorsque vous exécutez ./gradlew build, Gradle crée un processus enfant Java/Kotlin qui exécute KaptExecution. À ce moment-là, les annotation processors sont chargés, les annotations sont analysées et des fichiers sont générés dans le dossier build/generated/source/kapt.

Principales causes de l'erreur KaptExecution

L'erreur peut être provoquée par différents facteurs. Examinons les scénarios les plus courants.

1. Conflit de versions entre Kotlin et Kapt

Kapt fait partie du Kotlin Gradle Plugin. Si la version du plugin ne correspond pas à la version de Kotlin, le processor peut échouer. Par exemple :

// Incorrect\nplugins {\n    kotlin("jvm") version "1.8.20"\n    kotlin("kapt") version "1.9.0" // conflit\n}\n

Solution : les versions doivent correspondre.

2. Mémoire insuffisante pour le traitement des annotations

KaptExecution lance un processus JVM séparé. Si vous traitez beaucoup d'annotations (par exemple, Room avec des dizaines d'entités), le heap peut être insuffisant. Dans les logs, vous verrez OutOfMemoryError.

Solution : augmentez la mémoire pour le daemon Gradle dans gradle.properties :

org.gradle.jvmargs=-Xmx4g -XX:MaxPermSize=512m\nkapt.use.worker.api=false\n

3. Bugs dans l'annotation processor

Parfois, le processor lui-même (par exemple, une ancienne version de Dagger ou Room) contient des erreurs. Elles se manifestent uniquement avec certaines structures de code.

Exemple : une dépendance cyclique dans Dagger peut provoquer une StackOverflowError à l'intérieur de KaptExecution.

// Exemple de code problématique\n@Module\nclass MyModule {\n    @Provides\n    fun provideA(b: B): A = A(b)\n\n    @Provides\n    fun provideB(a: A): B = B(a) // dépendance cyclique\n}\n

KaptExecution échouera avec le message Circular dependency detected. La solution est de reconcevoir le graphe de dépendances.