Markdown Edit

Gradle Build System

Gradle is an open-source build automation tool primarily used for JVM projects (Java, Kotlin, Scala) with declarative Kotlin DSL (build.gradle.kts) and Groovy DSL support, incremental compilation, build caching, and configuration caching.

Caching Architecture

Gradle splits its persistent state across two directory trees:

Global User Home (~/.gradle/):
- ~/.gradle/caches/modules-2/: Downloaded external Maven/Ivy artifacts and metadata (files-2.1/).
- ~/.gradle/caches/<version>/jars-9/: Instrumented and transformed plugin and buildscript JARs loaded by Gradle's classloader hierarchy.
- ~/.gradle/caches/<version>/kotlin-dsl/: Compiled Kotlin DSL buildscript classes (build.gradle.kts, settings.gradle.kts).
- ~/.gradle/caches/build-cache-1/: Local task output build cache (org.gradle.caching=true).
- ~/.gradle/daemon/<version>/: Long-lived background Gradle Daemon JVM processes and lock registries.
Project-Local Directory (<project>/.gradle/):
- <project>/.gradle/configuration-cache/: Serialized task graphs and classloader scopes (org.gradle.configuration-cache=true).
- <project>/.gradle/<version>/: Project-scoped incremental build state and file hashes.

Troubleshooting: Deleting `~/.gradle/caches/` While a Daemon is Running

Manually deleting $HOME/.gradle/caches/ while a background Gradle Daemon is still running — or while <project>/.gradle/configuration-cache/ retains serialized state — causes subsequent builds to fail with ClassNotFoundException or PluginInstantiationException even after Gradle re-downloads the dependency JARs.

Error Symptoms

Missing Plugin Implementation Class (PluginInstantiationException):

* What went wrong:
An exception occurred applying plugin request [id: 'org.graalvm.buildtools.native', version: '1.1.12']
> Could not find implementation class 'org.graalvm.buildtools.gradle.NativeImagePlugin' for plugin 'org.graalvm.buildtools.native' specified in jar:file:/home/.../.gradle/caches/modules-2/files-2.1/org.graalvm.buildtools/native-gradle-plugin/1.1.12/.../native-gradle-plugin-1.1.12.jar!/META-INF/gradle-plugins/org.graalvm.buildtools.native.properties.

Missing Compiled Buildscript Task Class in VisitableURLClassLoader:

* What went wrong:
Error while reading task graph
> Exception while loading configuration for :common: Class 'Build_gradle$GenerateVersionTask' not found in class loader 'VisitableURLClassLoader(...)' of type 'org.gradle.internal.classloader.VisitableURLClassLoader'.

Root Cause

Gradle does not load plugin classes directly from the raw artifact in ~/.gradle/caches/modules-2/files-2.1/.../*.jar. Instead, InstrumentingClasspathFileTransformer instruments plugin JARs into ~/.gradle/caches/<version>/jars-9/<hash>/*.jar.
The long-lived Gradle Daemon JVM caches both the JAR instrumentation mapping and the VisitableURLClassLoader instances in memory (DefaultClassLoaderCache) across builds.
When rm -r $HOME/.gradle/caches/ is executed while a daemon is alive:
1. On the next invocation, Gradle re-downloads the raw artifact into ~/.gradle/caches/modules-2/files-2.1/ and reads META-INF/gradle-plugins/<id>.properties to identify the plugin's implementation class name.
2. However, the running daemon reuses its in-memory cached ClassLoader (or skips regenerating ~/.gradle/caches/<version>/jars-9/ because its in-memory cache believes the JAR was already instrumented), attempting to load classes from unlinked files in the deleted jars-9/ or kotlin-dsl/ directories.
3. Additionally, if org.gradle.configuration-cache=true is enabled, <project>/.gradle/configuration-cache/ stores references to those deleted jars-9/ and kotlin-dsl/ entries (and can even persist a broken configuration cache entry after a failed build).

Resolution

Whenever clearing ~/.gradle/caches/, always stop all running Gradle Daemons and remove the project-local .gradle/ directory (especially .gradle/configuration-cache/):

gradle --stop
rm -rf ~/.gradle/caches/ .gradle/

If using Nix and direnv:

direnv exec . gradle --stop
rm -rf ~/.gradle/caches/ .gradle/