Gradle Error: Unable to delete file – solution for Kotlin

Introduction: The familiar pain of every Android developer

You run Build → Clean Project in Android Studio, hoping for a quick project rebuild, but instead you see red text in the Build window:

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

Familiar? If you write in Kotlin for Android, this error can occur with alarming regularity, especially on Windows. It not only slows down development but also forces you to look for "magical" solutions like restarting your computer.

In this article, we will break down why the Unable to delete file error occurs, how to fix it once and for all, and show code examples in Kotlin for automating the solution. By the end of the article, you will be able not only to fix the problem but also to prevent it.

Let's start with the causes, then move on to solutions — from simple to advanced.

Why can't Gradle delete the file?

The Unable to delete file error when running the :app:clean task occurs when Gradle tries to clean the build/ folder but cannot delete one or more files. The main reasons:

\n
• The file is locked by another process — most often this is an antivirus, Windows Search Indexer, or Android Studio itself.
\n
• Long paths (Windows) — if the file path exceeds 260 characters, Windows may refuse to delete it.
\n
• Unclosed input/output streams — your application or library may be holding the file open.
\n
• Conflict with Instant Run / Apply Changes — older versions of Android Studio could lock files.
\n

Most often the problem appears on Windows, but it can also occur on macOS/Linux when using SMB shares or Docker.

Quick solutions (5 minutes)

Before diving into the code, try these simple steps. They help in 80% of cases.

1. Close Android Studio and delete manually

The most reliable way is to close the IDE and manually delete the app/build folder. If the file does not delete, use Unlocker (Windows) or the lsof command (macOS/Linux) to find the blocking process.

2. Use the terminal instead of the GUI

Sometimes Android Studio "freezes" on the clean task. Run the command in the terminal:

./gradlew clean --no-daemon

The --no-daemon flag runs Gradle without a background process, which often solves the locking problem.

3. Disable Instant Run / Apply Changes

In Android Studio 3.x and older, Instant Run could lock files. Disable it:

\n
• Go to File → Settings → Build, Execution, Deployment → Instant Run.
\n
• Uncheck Enable Instant Run.
\n

In newer versions (Arctic Fox+), this option is replaced by Apply Changes, but the problem occurs less frequently.

Advanced solutions: automation in Kotlin

If the quick methods didn't help, it's time to automate the process. We'll write a small script in Kotlin that will run before the clean task and forcibly close blocking processes.

4. Using Kotlin DSL in Gradle for a custom task

Add the following code to the build.gradle.kts file (module level):

// build.gradle.kts (app level)\ntasks.register<Exec>("killFileLocks") {\n    description = "Closes processes blocking files in the build folder"\n    commandLine("cmd", "/c", "taskkill /f /im java.exe 2>nul || exit 0")\n    // For macOS/Linux replace with:\n    // commandLine("sh", "-c", "lsof -ti:8080 | xargs kill -9 2>/dev/null || true")\n}\n\ntasks.named("clean") {\n    dependsOn