Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 36 ยท Projects and Practice

Troubleshooting Gradle Builds: Errors, Commands and Practice

Fix common Gradle problems: dependency resolution, version conflicts, out of memory, stale caches, wrapper issues, plus a command cheat sheet and practice exercises with runnable stand-ins.

Every Gradle user meets confusing errors. Most of them fall into a few families: something could not be resolved, two things conflict, something ran out of resources, or a cache or daemon holds stale state. This lesson gives you a systematic way to diagnose them, a cheat sheet of commands, and practice exercises with runnable models.

It closes chapter 9. It draws on everything before it, especially dependencies in multi-project builds, caching and performance.

Gradle cannot run on this site. Commands and messages are shown read-only. Error message wording changes slightly between Gradle versions, so look for the key phrases.

A diagnosis routine

  1. Read the first error, not the last. Gradle prints What went wrong: and a cause chain. The deepest Caused by: is usually the real problem.
  2. Rerun with more detail: --stacktrace for the Java stack trace, --info for decisions, --debug only as a last resort.
  3. Reduce: run a single task and project (./gradlew :core:compileJava).
  4. Check the environment: ./gradlew --version (Gradle, JVM, OS) and java -version.
  5. Isolate state: ./gradlew --stop, then ./gradlew build --no-build-cache --rerun-tasks to rule out caches.
  6. Search the exact message in the Gradle docs and the plugin's issue tracker.

Family 1: dependency resolution

TEXT
Could not resolve com.example:lib:1.2.3.
Required by: project :app
> Could not resolve com.example:lib:1.2.3.
   > Could not GET 'https://repo.maven.apache.org/.../lib-1.2.3.pom'. Received status code 404

Causes and fixes:

  • Wrong coordinates or version: check the repository's web page for the exact group, name and version.
  • Missing repository: add mavenCentral() (or the company repo) to repositories {} in the right place; plugin repositories belong in pluginManagement.
  • Offline or proxy problems: check network settings, --offline only when you truly are offline.
  • A stale negative cache: run ./gradlew build --refresh-dependencies.

Useful commands:

TEXT
./gradlew :app:dependencies --configuration runtimeClasspath
./gradlew :app:dependencyInsight --dependency lib --configuration runtimeClasspath

Family 2: conflicts and wrong versions

Symptoms: NoSuchMethodError, ClassNotFoundException, or a library version you did not choose.

  • dependencyInsight shows who requested which version and why the winner was chosen (Gradle picks the highest requested version).

  • Pin a version with a constraint:

    Kotlin
    dependencies {
        constraints {
            implementation("com.fasterxml.jackson.core:jackson-databind:2.18.2") {
                because("older versions are requested transitively and have a known bug")
            }
        }
    }
    
  • Exclude a bad transitive dependency: implementation("a:b:1") { exclude(group = "x", module = "y") }.

  • Use a BOM (platform()) to align a family of libraries.

  • Fail on unexpected conflicts with configurations.all { resolutionStrategy.failOnVersionConflict() } while debugging.

Java Stand-in: which version wins and who asked for it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Family 3: resources

Message Meaning Fix
Java heap space / OutOfMemoryError in the daemon Gradle's JVM is too small org.gradle.jvmargs=-Xmx3g in gradle.properties
Metaspace many classes loaded add -XX:MaxMetaspaceSize=768m
OOM in tests the test JVM, not Gradle tasks.test { maxHeapSize = "1g" }
Daemon will be stopped at the end of the build after running out of JVM memory memory pressure reduce parallel forks or raise memory
Timeout waiting to lock ... another process holds a lock stop daemons; check for a hung IDE sync

Family 4: Java version and toolchains

TEXT
Unsupported class file major version 69
Cannot find a Java installation on your machine matching: {languageVersion=21}
error: invalid source release: 25
  • Gradle itself needs a compatible JDK; check the compatibility table in the Gradle documentation and upgrade the wrapper if your JDK is newer.
  • Install the JDK you request in java { toolchain { ... } } or add a toolchain resolver plugin in settings.gradle.kts so Gradle can download it.
  • Make sure the IDE uses the same Gradle JVM as the command line.

Family 5: wrapper, caches and state

  • ./gradlew: Permission denied: chmod +x gradlew and commit the mode.
  • Corrupt download: delete ~/.gradle/wrapper/dists/<version> and rerun.
  • Weird stale behavior: ./gradlew clean, then --rerun-tasks; as a last resort delete the project's .gradle/ and build/ folders (not ~/.gradle first).
  • IDE out of sync: reload the Gradle project and invalidate caches in the IDE.

Family 6: configuration errors

  • Could not find method foo() for arguments [...] means the DSL block or plugin is missing in this script (applied the wrong plugin, or the plugin is not applied yet).
  • Unresolved reference: libs means the catalog file is not at gradle/libs.versions.toml or a name has a typo.
  • Task with name 'x' not found means a typo or a plugin that was not applied in that project; list tasks with ./gradlew :proj:tasks --all.
  • Circular dependency between the following tasks means cyclic project or task dependencies; see the multi-project lessons.

Command cheat sheet

Goal Command
List tasks ./gradlew tasks --all
Task details ./gradlew help --task test
Project tree ./gradlew projects
What would run? ./gradlew build --dry-run
Dependency tree ./gradlew dependencies --configuration runtimeClasspath
Why is X here? ./gradlew dependencyInsight --dependency X
Ignore caches ./gradlew build --no-build-cache --rerun-tasks
Refresh remote modules ./gradlew build --refresh-dependencies
Continue after failure ./gradlew build --continue
Profile ./gradlew build --profile
Build scan ./gradlew build --scan
Stop daemons ./gradlew --stop
Show Gradle version ./gradlew --version

Practice exercises

Try each one on a small project of your own. Answers follow below.

  1. A teammate adds implementation("org.apache.commons:commons-lang3") and gets Could not find. What is missing, and how do you fix it two different ways?
  2. ./gradlew test prints NO-SOURCE for test. Give two reasons.
  3. Your build prints Task :jar UP-TO-DATE even though you changed src/main/resources/app.properties. What do you check?
  4. The CI build fails with Could not resolve all files for configuration ':app:runtimeClasspath' but local builds pass. List three causes.
  5. Make ./gradlew check run an integrationTest task you already wrote.
Java Stand-in: check your answers to exercise 1 and 5

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Answers

  1. The version is missing. Either write the full coordinate org.apache.commons:commons-lang3:3.17.0, or add a platform/BOM or version catalog entry that supplies it.
  2. There is no src/test code (no source files), or the test source set is empty because the files are in the wrong folder or package layout.
  3. Check that the file is really in src/main/resources of the project that builds the jar, that processResources ran, and that you are looking at the right module. Gradle hashes content, so an edit does change the fingerprint.
  4. A repository only configured locally (for example mavenLocal()), credentials missing in CI for a private repository, a network or proxy restriction, or a dependency that was removed or is a snapshot.
  5. tasks.check { dependsOn("integrationTest") } (or the suite reference from the test suites lesson).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command explains why a particular library version was selected?

    dependencyInsight shows every request for the module and the rule that chose the winning version.
  2. 2. Your tests fail with OutOfMemoryError. Which setting do you change?

    Tests run in a forked JVM configured on the Test task, while org.gradle.jvmargs sizes the Gradle daemon.
  3. 3. What does --refresh-dependencies do?

    It forces Gradle to revalidate cached dependency information, which helps with stale or negative cache entries.
  4. 4. Where should you start reading a long Gradle error?

    The first What went wrong section and the deepest cause usually name the real problem.

Summary

  • Diagnose in steps: read the cause chain, rerun with --stacktrace or --info, narrow to one task, rule out caches.
  • Dependency errors: check coordinates, repositories and use dependencies and dependencyInsight; pin with constraints.
  • Memory errors: size the daemon with org.gradle.jvmargs and test JVMs with maxHeapSize.
  • Java version errors: use toolchains and a compatible Gradle.
  • Keep the cheat sheet nearby, and practice on small projects.

Next: back to the Gradle track overview