Error de Gradle: Unable to delete file – solución para Kotlin

Introducción: El dolor familiar de todo desarrollador Android

Ejecutas Build → Clean Project en Android Studio, esperando una reconstrucción rápida del proyecto, pero en su lugar ves texto rojo en la ventana Build:

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

¿Te suena familiar? Si escribes en Kotlin para Android, este error puede aparecer con una frecuencia alarmante, especialmente en Windows. No solo ralentiza el desarrollo, sino que también te obliga a buscar soluciones «mágicas» como reiniciar la computadora.

En este artículo, analizaremos por qué ocurre el error Unable to delete file, cómo solucionarlo de forma definitiva y mostraremos ejemplos de código en Kotlin para automatizar la solución. Al final del artículo, no solo podrás solucionar el problema, sino también prevenirlo.

Empecemos con las causas, luego pasemos a las soluciones, desde las simples hasta las avanzadas.

¿Por qué Gradle no puede eliminar el archivo?

El error Unable to delete file al ejecutar la tarea :app:clean ocurre cuando Gradle intenta limpiar la carpeta build/, pero no puede eliminar uno o más archivos. Las causas principales son:

\n
• El archivo está bloqueado por otro proceso — generalmente es el antivirus, Windows Search Indexer, o el propio Android Studio.
\n
• Rutas largas (Windows) — si la ruta del archivo supera los 260 caracteres, Windows puede negarse a eliminarlo.
\n
• Flujos de entrada/salida no cerrados — tu aplicación o biblioteca puede mantener el archivo abierto.
\n
• Conflicto con Instant Run / Apply Changes — versiones antiguas de Android Studio podían bloquear archivos.
\n

La mayoría de las veces, el problema se manifiesta en Windows, pero también puede ocurrir en macOS/Linux al usar recursos compartidos SMB o Docker.

Soluciones rápidas (en 5 minutos)

Antes de meterse con el código, prueba estos pasos simples. Ayudan en el 80% de los casos.

1. Cierra Android Studio y elimina manualmente

La forma más segura es cerrar el IDE y eliminar manualmente la carpeta app/build. Si el archivo no se elimina, usa Unlocker (Windows) o el comando lsof (macOS/Linux) para encontrar el proceso bloqueador.

2. Usa la terminal en lugar de la GUI

A veces Android Studio se «cuelga» en la tarea clean. Ejecuta el comando en la terminal:

./gradlew clean --no-daemon

La bandera --no-daemon ejecuta Gradle sin el proceso en segundo plano, lo que a menudo resuelve el problema de bloqueo.

3. Desactiva Instant Run / Apply Changes

En Android Studio 3.x y versiones anteriores, Instant Run podía bloquear archivos. Desactívalo:

\n
• Ve a File → Settings → Build, Execution, Deployment → Instant Run.
\n
• Desmarca la casilla Enable Instant Run.
\n

En las versiones nuevas (Arctic Fox+), esta opción se reemplazó por Apply Changes, pero el problema es menos frecuente.

Soluciones avanzadas: automatización en Kotlin

Si los métodos rápidos no funcionaron, es hora de automatizar el proceso. Escribiremos un pequeño script en Kotlin que se ejecutará antes de la tarea clean y forzará el cierre de los procesos bloqueadores.

4. Usamos Kotlin DSL en Gradle para una tarea personalizada

Agrega al archivo build.gradle.kts (a nivel de módulo) el siguiente código:

// build.gradle.kts (app level)\ntasks.register<Exec>("killFileLocks") {\n    description = "Cierra los procesos que bloquean archivos en la carpeta build"\n    commandLine("cmd", "/c", "taskkill /f /im java.exe 2>nul || exit 0")\n    // Para macOS/Linux reemplaza con:\n    // commandLine("sh", "-c", "lsof -ti:8080 | xargs kill -9 2>/dev/null || true")\n}\n\ntasks.named("clean") {\n    dependsOn