Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Gradle wrapper cannot create the folder for its lock file

ErrorCould not create parent directory for lock file .../wrapper/dists/gradle-8.x-bin/.../gradle-8.x-bin.zip.lck

Short answer

The Gradle wrapper keeps its downloaded distribution under the Gradle user home and needs to create a wrapper/dists folder there. The error means that folder could not be created: GRADLE_USER_HOME points somewhere invalid, or a plain file sits where a folder belongs. Read the path in the message, then fix that path.

  • Applies to Gradle 8.x, Gradle 9, Android Studio, Windows 11, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the full path in the message: the part before wrapper/dists is the Gradle user home Gradle chose. Then compare it with the environment variable and with what exists on disk.

    echo "$GRADLE_USER_HOME"
    ls -ld ~/.gradle ~/.gradle/wrapper
  2. 2Match what you see, then jump to its fix

    1. 1The path in the message is not ~/.gradle, for example a drive that is missing, a system folder, or a typoGRADLE_USER_HOME points to a path that cannot be createdFix
    2. 2ls shows wrapper (or dists) as a file, not a folder, inside the Gradle user homeA regular file is in the way of the wrapper folderFix
    3. 3Builds from one tool (shell, IDE or CI job) fail while another one worksAnother tool uses a different Gradle user home than your shellFix

What does the error look like?

  • Could not create parent directory for lock file .../wrapper/dists/gradle-8.x-bin/.../gradle-8.x-bin.zip.lck

Cause 1 of 3

GRADLE_USER_HOME points to a path that cannot be created

1Check

Gradle stores caches, daemon files and wrapper distributions in its user home. It defaults to .gradle in your home folder, and the GRADLE_USER_HOME environment variable overrides it. A -Dgradle.user.home setting is applied before that.

echo "$GRADLE_USER_HOME"
env | grep -i gradle

2Fix

Unset the variable to get the default location, or set it to a folder your user can create and write. Close and reopen the terminal and the IDE, so they pick up the new value.

unset GRADLE_USER_HOME
# or choose a folder you own:
export GRADLE_USER_HOME="$HOME/.gradle"

3Verify

Run the wrapper again from the project folder.

./gradlew --version

Confirmed by docs.gradle.org

Did this fix it?

Cause 2 of 3

A regular file is in the way of the wrapper folder

1Check

The wrapper has to create wrapper/dists inside the user home. If a regular file already uses the name wrapper, the folder cannot be created, and the message does not say why.

ls -l "${GRADLE_USER_HOME:-$HOME/.gradle}"
file "${GRADLE_USER_HOME:-$HOME/.gradle}/wrapper"

2Fix

Move the file away (rename it, do not delete it blindly), then run the wrapper so it creates the folder itself.

mv "${GRADLE_USER_HOME:-$HOME/.gradle}/wrapper" "${GRADLE_USER_HOME:-$HOME/.gradle}/wrapper.old"
./gradlew --version

3Verify

The wrapper downloads the distribution and prints the Gradle version.

ls "${GRADLE_USER_HOME:-$HOME/.gradle}/wrapper/dists"

Confirmed by github.com

Did this fix it?

Cause 3 of 3

Another tool uses a different Gradle user home than your shell

1Check

The location can come from the -Dgradle.user.home system property as well as the environment variable, so two tools can end up with two different homes. List what the shell sees and compare it with the failing tool.

env | grep -i gradle

2Fix

Make every tool use the default Gradle user home, or point all of them to the same writable folder.

# same folder for both
export GRADLE_USER_HOME="$HOME/.gradle"

3Verify

Run the wrapper in the shell and in the failing tool; both should find the same distribution.

./gradlew --version

Confirmed by docs.gradle.org

Did this fix it?

How do I stop it coming back?

  • Set GRADLE_USER_HOME only when you have a reason, and keep it on a local, always-mounted, writable disk.
  • In CI, point GRADLE_USER_HOME at the workspace or cache folder the job owns.
  • Do not store files named wrapper or caches inside the Gradle user home by hand.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

adb tcpip 5555 fails because no device is found

adb: more than one device/emulator

adb tcpip only works while the device is attached and listed by adb, because it tells the phone to start listening on port 5555.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.