Erro Gradle: Unable to delete file – solução para Kotlin

Introdução: A dor familiar de todo desenvolvedor Android

Você executa Build → Clean Project no Android Studio, esperando uma reconstrução rápida do projeto, mas em vez disso vê o texto vermelho na janela Build:

Error: Execution failed for task ':app:clean'.\n> Unable to delete file: C:\\Users\\User\\AndroidStudioProjects\\MyApp\\app\\build\\...\\some_file.dex

Familiar? Se você programa em Kotlin para Android, esse erro pode ocorrer com uma frequência assustadora, especialmente no Windows. Ele não apenas retarda o desenvolvimento, mas também faz você procurar soluções "mágicas" como reiniciar o computador.

Neste artigo, vamos analisar por que ocorre o erro Unable to delete file, como corrigi-lo de uma vez por todas e mostrar exemplos de código em Kotlin para automatizar a solução. Ao final do artigo, você será capaz não apenas de corrigir o problema, mas também de preveni-lo.

Vamos começar pelas causas e depois passar para as soluções — das simples às avançadas.

Por que o Gradle não consegue excluir o arquivo?

O erro Unable to delete file ao executar a tarefa :app:clean ocorre quando o Gradle tenta limpar a pasta build/, mas não consegue excluir um ou mais arquivos. As principais causas são:

\n
• Arquivo bloqueado por outro processo — na maioria das vezes, é o antivírus, o Windows Search Indexer ou o próprio Android Studio.
\n
• Caminhos longos (Windows) — se o caminho do arquivo exceder 260 caracteres, o Windows pode se recusar a excluí-lo.
\n
• Fluxos de entrada/saída não fechados — seu aplicativo ou biblioteca pode estar mantendo o arquivo aberto.
\n
• Conflito com Instant Run / Apply Changes — versões antigas do Android Studio podiam bloquear arquivos.
\n

Na maioria das vezes, o problema se manifesta no Windows, mas também pode ocorrer no macOS/Linux ao usar compartilhamento SMB ou Docker.

Soluções rápidas (em 5 minutos)

Antes de mexer no código, tente estas etapas simples. Elas ajudam em 80% dos casos.

1. Feche o Android Studio e exclua manualmente

A maneira mais confiável é fechar a IDE e excluir manualmente a pasta app/build. Se o arquivo não for excluído, use Unlocker (Windows) ou o comando lsof (macOS/Linux) para encontrar o processo bloqueador.

2. Use o terminal em vez da GUI

Às vezes, o Android Studio "trava" na tarefa clean. Execute o comando no terminal:

./gradlew clean --no-daemon

A flag --no-daemon executa o Gradle sem o processo em segundo plano, o que geralmente resolve o problema de bloqueio.

3. Desative o Instant Run / Apply Changes

No Android Studio 3.x e versões anteriores, o Instant Run podia bloquear arquivos. Desative-o:

\n
• Vá para File → Settings → Build, Execution, Deployment → Instant Run.
\n
• Desmarque a opção Enable Instant Run.
\n

Nas versões mais recentes (Arctic Fox+), esta opção foi substituída por Apply Changes, mas o problema é menos comum.

Soluções avançadas: automação em Kotlin

Se os métodos rápidos não ajudaram, é hora de automatizar o processo. Vamos escrever um pequeno script em Kotlin que será executado antes da tarefa clean e forçará o fechamento dos processos bloqueadores.

4. Usando Kotlin DSL no Gradle para uma tarefa personalizada

Adicione ao arquivo build.gradle.kts (nível do módulo) o seguinte código:

// build.gradle.kts (app level)\ntasks.register<Exec>("killFileLocks") {\n    description = "Fecha processos que bloqueiam arquivos na pasta build"\n    commandLine("cmd", "/c", "taskkill /f /im java.exe 2>nul || exit 0")\n    // Para macOS/Linux, substitua por:\n    // commandLine("sh", "-c", "lsof -ti:8080 | xargs kill -9 2>/dev/null || true")\n}\n\ntasks.named("clean") {\n    dependsOn