KaptExecution em Kotlin: o que está por trás do erro do Gradle

Introdução: por que o KaptExecution quebra a build e como corrigir

Se você já se deparou com o erro A failure occurred while executing org.jetbrains.kotlin.gradle.internal.KaptExecution, sabe como isso tira do sério. A build falha, o Gradle exibe texto vermelho e nos logs — stacktraces confusos. No Stack Overflow, essa pergunta acumulou milhares de visualizações, mas a maioria das respostas é apenas "tente limpar o cache". Nós iremos além.

Neste artigo, não vamos apenas dar soluções prontas. Vamos olhar por dentro do mecanismo Kapt (Kotlin Annotation Processing Tool) e entender exatamente o que acontece quando o Gradle executa KaptExecution. Você aprenderá como funciona a geração de código, onde se escondem os erros típicos e como preveni-los. E o principal — receberá exemplos funcionais em Kotlin que podem ser aplicados imediatamente no seu projeto.

Este é um material educacional para pythonlib.ru, adaptado para desenvolvedores que querem não apenas copiar comandos, mas entender o que acontece dentro do builder.

O que é KaptExecution e para que serve

Kapt é um plugin para Kotlin que permite usar annotation processors compatíveis com Java (por exemplo, Dagger, Room, Glide, Moshi) em projetos Kotlin. Quando você escreve uma anotação @Inject ou @Entity, o compilador gera código adicional (classes, fábricas, DAOs).

Internamente no Gradle, o Kapt funciona como uma tarefa separada. Quando você executa a build, o Gradle chama KaptExecution — este é o comando que executa o compilador Kotlin com o processamento de anotações ativado. Se algo der errado nesta etapa (por exemplo, o processor lançou uma exceção ou a memória acabou), você vê o tal erro.

Como o KaptExecution aparece no Gradle

No arquivo build.gradle.kts (ou build.gradle), o Kapt é adicionado assim:

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

Quando você executa ./gradlew build, o Gradle cria um processo filho Java/Kotlin que executa KaptExecution. Neste momento, os annotation processors são carregados, as anotações são analisadas e os arquivos são gerados na pasta build/generated/source/kapt.

Principais causas do erro KaptExecution

O erro pode ser causado por diferentes fatores. Vamos considerar os cenários mais comuns.

1. Conflito de versões do Kotlin e Kapt

Kapt faz parte do Kotlin Gradle Plugin. Se a versão do plugin não corresponder à versão do Kotlin, o processor pode falhar. Por exemplo:

// Incorreto\nplugins {\n    kotlin("jvm") version "1.8.20"\n    kotlin("kapt") version "1.9.0" // conflito\n}\n

Solução: as versões devem coincidir.

2. Memória insuficiente para o annotation processing

KaptExecution executa um processo JVM separado. Se você estiver processando muitas anotações (por exemplo, Room com dezenas de entidades), o heap pode ser insuficiente. Nos logs, você verá OutOfMemoryError.

Solução: aumente a memória para o daemon do Gradle no gradle.properties:

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

3. Bugs no annotation processor

Às vezes, o próprio processor (por exemplo, uma versão antiga do Dagger ou Room) contém erros. Eles se manifestam apenas com determinadas estruturas de código.

Exemplo: uma dependência cíclica no Dagger pode causar StackOverflowError dentro do KaptExecution.

// Exemplo de código problemático\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) // dependência cíclica\n}\n

KaptExecution falhará com a mensagem Circular dependency detected. Solução — redesenhar o grafo de dependências