Gradle Best Practices & Troubleshooting

Forty-seven items are easier to remember as six habits.

The practice (added to the list in 9.6.0) says: do not use project.afterEvaluate {} to configure tasks, wire properties or react to plugin application; use lazy properties and pluginManager.withPlugin(). The official reasons are that the order of several afterEvaluate callbacks is the order of registration, so a callback can see stale configuration; that tasks configured inside it are touched eagerly even if they never run; and that it is incompatible with the configuration cache. It lists two narrow cases where it is still acceptable, fail-fast validation and reporting, and asks you to file a bug if the lazy APIs do not cover your case.

The reason people reach for afterEvaluate is that a value is set after the task that reads it has been defined. A Property solves that without a callback: the task holds the property, the value is read when the task runs, and it does not matter which line sets it.

To react to another plugin without afterEvaluate, use pluginManager.withPlugin("java") { ... }, which runs immediately if the plugin is already applied and as soon as it is applied otherwise (the details are in Build Lifecycle and Lazy Configuration & Providers). A pitfall of the Groovy version: a plain bannerText = 'text' on a local def variable replaces the variable with a String (the build then fails with No signature of method: java.lang.String.get(), which is what the first attempt of this example did); a Property held in a local variable has to be set with set(). Task properties, in contrast, accept = in both DSLs.

The run (Kotlin DSL; the second run of the build, so the configuration cache entry was reused, which shows that the example is compatible with it; Groovy printed the same lines):

Source: Gradle: Avoid afterEvaluate

The practice "Don’t access a Project instance during Task Execution" (9.7.0) is the most common reason for a build to be rejected by the configuration cache. The project is a live object of the configuration phase, and a cached build does not have it. Here is the mistake, in a task that prints the project version in doLast, and the fix, which copies the value into a local variable while the task is being configured:

With the configuration cache on, the first one fails (the second one is the run shown in the previous section):

The Groovy run fails the same way. The differences are that the problem line names the build file and the line (Build file 'build.gradle': line 37: invocation of 'Task.project' ...), that the failure has a Where: section with Build file '<work>/tidepool/build.gradle' line: 37, and that the registration is reported as (registered in build file 'build.gradle'). That last parenthesis is the task provenance added to error messages in Gradle 9.5.0; the 8.14 output has no such text (not run here, from the release notes). The error message and the link to the explanation are the same in 8.14 (the configuration cache has been stable since 8.1). In a build that has just been taken to 9.x, --no-configuration-cache makes the failure disappear without fixing it, so the right reaction is to read the report whose location is printed, not to switch the cache off. The cache itself is the subject of Configuration Cache & Isolated Projects.

Source: Gradle: Don’t access a Project instance during Task Execution and Gradle: Configuration cache requirements, using the project during execution

"Build output should be byte-for-byte reproducible" (9.7.0) is a security and a performance practice at once: if the same source produces the same bytes, anybody can check a binary against the source, and the build cache and the up-to-date checks work on stable inputs. The two usual causes of difference in a JAR are the timestamps of the entries and their order. Since Gradle 9.0.0 archive tasks are reproducible by default: timestamps are not preserved and the order of the entries is sorted. In Gradle 8.14 they were not (the 9.0.0 release notes list it as a change of default; not run here).

To see the effect, build the JAR of tidepool-model twice, two seconds apart, with a clean before each build, and compare the first 16 hex digits of the SHA-256 sum. Then do it with a switch that restores the old behaviour for archive tasks.

The first pair of lines is identical with both DSLs (875ec791c2960e71 each time, in two separate builds in two projects with identical sources); with the switch on, the checksum changes on every build (the two Groovy runs gave 4bd70f84d92097fe and 4c0164d51b4e07f6). Two things follow. If a build must produce a checksum that someone else can reproduce, do not turn the archive options back on; and what remains of non-determinism is outside the archive settings: the JDK that compiled the classes (a toolchain pins it, see Gradle Toolchains), generated files that contain a timestamp or a host name, and the order in which a custom task writes its output. The same advice for Maven is in Maven Security & Reproducible Builds, and publishing is in Publishing.

Source: Gradle: Build output should be byte-for-byte reproducible and Gradle: Upgrading to Gradle 9.0.0, reproducible archives by default

Two security practices concern the wrapper, which runs before any safeguard of your build: set distributionSha256Sum (added to the list in 9.1.0), and validate the wrapper on every upgrade (9.3.0). The JAR is a binary that is checked into the repository, so a change to it deserves the review you would give to any executable. Gradle publishes the checksum of the wrapper JAR and of each distribution next to the release (https://gradle.org/release-checksums/, and as plain text files at https://services.gradle.org/distributions/gradle-9.8.1-wrapper.jar.sha256 and ...-bin.zip.sha256). Compare the checksum of the checked-in JAR with the published one:

The two values are equal, and equal to the one on the release-checksums page. The value of distributionSha256Sum in the starter configuration, dce76f55...c01f, is the one published for the -bin zip. The second check recommended by the official page is to regenerate the wrapper with a Gradle that you trust and compare the files. Here a Gradle 9.8.1 installation (not the project’s wrapper) regenerated the wrapper in an empty project with gradle wrapper --gradle-version 9.8.1 --gradle-distribution-sha256-sum <sum> --no-validate-url, and cmp found gradlew, gradlew.bat and gradle-wrapper.jar byte-identical to the ones in the project. The properties file differed only in distributionUrl, because the examples' wrapper downloads from a local file, not from services.gradle.org; the page shows the official address. In a pull request, a change to the JAR or to distributionUrl that has no matching Gradle upgrade is a red flag. For GitHub Actions the official setup action (v4 or newer) validates every gradle-wrapper.jar in the repository automatically (not run here); see CI & IDE Integration for the CI side.

The related practice is "Do not run ./gradlew on untrusted projects" (9.7.0): the wrapper script, the JAR and every build script execute arbitrary code, and opening a project in an IDE runs a Gradle sync that does the same. Read the build scripts and gradle-wrapper.properties first, make sure distributionUrl points to https://services.gradle.org/, regenerate the wrapper with a trusted installation, or work in a container or a virtual machine. The same applies to Maven’s wrapper and to Ant build files you downloaded; see Supply-Chain Security.

Source: Gradle: Validate the Gradle distribution SHA-256 checksum, Gradle: Validate the Gradle Wrapper on every upgrade, Gradle: Do not run ./gradlew on untrusted projects and Gradle: Release checksums

Do not apply the list in one change. Adopt the cheap, mechanical items first (root project name, UTF-8, distributionSha256Sum, the plugins {} block), then the structural ones that touch many files (catalog, convention plugins), and use the deprecation warnings (--warning-mode all, see Command-Line Interface) and the configuration cache report to find the lazy-API and Project violations. The practice "Consider use of @Incubating APIs carefully" (9.7.0) cuts both ways: an incubating feature may change in a minor release, yet some of them, such as dependencyResolutionManagement.repositories, are recommended by the list itself. Check when a feature was introduced and how many open issues it has, as the official page suggests; the lifecycle labels are explained in Versions, Compatibility & Release History.

./gradlew --version is the first thing to run (Kotlin DSL and Groovy DSL are irrelevant here). With the wrapper, this also downloads the distribution the first time.

Three failures at this point, from the guide:

If --version works but every build fails with the same error, a configuration script is broken. ./gradlew help runs those scripts and no real task:

Source: Gradle: Troubleshooting the installation, Command not found, JAVA_HOME is set to an invalid directory, Permission denied and Other installation failures

Make a typing mistake in a project dependency (":tidepool-modle" instead of ":tidepool-model" in tidepool-engine/build.gradle.kts) and run help:

(One line, Starting a Gradle Daemon, 3 busy and 47 stopped Daemons could not be reused, was removed; it describes the other daemons of the machine.) Read it in this order: Where names the file and the line (the line of the project(...) call, not of the line that uses the result); What went wrong is the message; the Try: hints are generic. When the message is not enough, --stacktrace appends the exception and the full chain of calls (the first lines are shown here; the whole trace is about two hundred lines of internal frames):

The frames that matter are the first one from org.gradle.api (what failed) and the last ones before Program.execute (the build script frame, which names build.gradle.kts:6). Script compilation errors are worse: in the Kotlin DSL a typo in a block name (dependancies { ... }) reports Unresolved reference for the block and then for every call inside it, with the candidates of each overload, which can fill a screen. Look at the first error of the list only. The two DSLs are compared in Kotlin DSL and Groovy DSL & Migrating to Kotlin. In the Groovy DSL the same mistake gives the same Project with path ':tidepool-modle' could not be found message with Where: Build file '<work>/tidepool/tidepool-engine/build.gradle' line: 6, preceded by one more line in the What went wrong section, A problem occurred evaluating project ':tidepool-engine'.

Source: Gradle: Troubleshooting and Gradle: Command-line interface, debugging options

Set the version of commons-csv in gradle/libs.versions.toml to 9.9.9, which does not exist, and compile. With the configuration cache on, the failure surfaces while Gradle stores the task graph and is wrapped in a long Configuration cache state could not be cached message that contains the same text; to read the real one, run with --no-configuration-cache:

The message says what was asked (org.apache.commons:commons-csv:9.9.9), by whom (Required by: project ':tidepool-engine'), which configuration (compileClasspath), and where Gradle looked (a single .pom URL, because the build declares one repository). The causes are almost always one of: a typo in the version or the coordinates; a repository missing from dependencyResolutionManagement, or filtered out by content filtering (Repositories & Content Filtering); a snapshot that was never published; a proxy or credentials problem (Gradle prints the HTTP status in the message); or an artifact that exists without POM metadata, for which the Try: hint tells you to adjust metadataSources. The same build in offline mode shows the other side of the cache:

Offline mode uses only what is in the dependency cache; --refresh-dependencies forces the opposite (revalidate everything), and the cache, its expiry of dynamic versions and the lockfile and verification files are explained in Dependency Locking, Verification & Caching.

When the build resolves but picks a version you did not expect, ask Gradle why with dependencyInsight. This is the same build with the correct version (1.14.1):

The first block shows the variant that was selected and the attributes the consumer requested (Java 21, jar, java-runtime) against what the module provided; the second is the reverse tree, from the dependency to the configuration that needs it. When there is a conflict, this report also lists the selection reasons (for example a conflict resolution, a constraint or a forced version), which is the quickest way to find the constraint, BOM, catalog or substitution rule that decided; the mechanisms are in Dependency Resolution, Conflicts & Capabilities, Resolution Rules & Substitution and Variant-Aware Resolution & Module Metadata. The official guide also points to the Dependencies view of a Build Scan, which offers the same information with a search box (publishing a scan was not run here). Maven’s equivalents (dependency:tree, -X) are in Maven Troubleshooting & Best Practices.

Source: Gradle: Debugging dependency resolution and Gradle: Viewing and debugging dependencies, identifying the reason for a dependency selection

A task is skipped (UP-TO-DATE) when the values of its inputs, the contents of its input files and the state of its outputs equal those of the last execution. When a task runs although you changed nothing, --info prints why it is not up to date. Two tasks demonstrate the usual causes. stampUnstable takes the current time as an input; stampStable takes the project version; noOutputs has an action and declares no output.

The build was run once to fill the outputs, and then again with --info, filtering the very long output down to the explanations. These runs used --no-configuration-cache: with the cache on, the value of System.currentTimeMillis() is computed once, at configuration time, and stored in the cache entry, so a cache hit would freeze the "unstable" input and hide the problem (which is a different, quieter trap).

The output is identical with the Groovy DSL. The two reasons seen here are the most frequent in practice:

Other reasons are reported in the same place: an input file that was added, removed or changed; an output file that was changed or removed between runs (including by another task that writes to the same directory); and an explicit request to rerun (--rerun for one task, --rerun-tasks for all of them). The vocabulary and the inputs-and-outputs model are in Incremental Build; the meaning of the outcomes (UP-TO-DATE, FROM-CACHE, SKIPPED, NO-SOURCE) is in the command-line page. The Timeline view of a Build Scan gives the same explanation as a searchable page (not run here). A dry run shows what would run, in order, without running anything:

Source: Gradle: Task executed when it should have been UP-TO-DATE and Gradle: Command-line interface, rerunning tasks

The troubleshooting guide sends slow builds to the performance guide, which is the page Performance Profiling & Build Scans. A local first step that needs no account is --profile, which writes an HTML report with the time of each phase, each project and each task:

The report is a file under build/reports/profile/. The scan option (--scan) is more detailed, but it publishes the build to an external service after you accept its terms of use, so it was not run here. Most of the time lost in practice comes from the practices of this page that are about performance: no configuration cache (configuration repeated on every invocation), no build cache, expensive computation in the configuration phase, dependency resolution during configuration (the practice "Don’t resolve Configurations before Task Execution"), and an undersized or oversized daemon heap (The Gradle Daemon). Build output as a stream of > Task ... lines is lifecycle logging; --console=verbose keeps outcomes such as UP-TO-DATE on the console in an interactive terminal.

Source: Gradle: Troubleshooting slow builds and Gradle: Command-line interface, performance options

Build logic (a script, buildSrc, a plugin of an included build) is code, and it can be debugged like code. Set the org.gradle.debug property to true and the build starts a JVM that suspends until a remote debugger attaches to port 5005 (org.gradle.debug.port changes the port; org.gradle.debug.host sets the interface, and * listens on all of them, which exposes the build to the network, so use it only when you must). The Kotlin DSL scripts can be debugged too, not only the plugin classes. This run used a Gradle User Home created for it (so that the shared daemons were not touched) and was ended after the line appeared, since no debugger was attached (an IDE attach was not run here):

The JVM listens on 127.0.0.1:5005 only (confirmed with lsof in this run), and then waits. In an IDE, create a Remote JVM Debug configuration for that port and set breakpoints in the plugin or script source. The JVM stays suspended until a debugger attaches or you kill it (here the daemon and the client were ended by killing their processes).

For logs, raise the level (--info, --debug, --warning-mode all), and remember that the daemon writes its own log to $GRADLE_USER_HOME/daemon/<version>/daemon-<pid>.out.log. If the build fails before any task, with a message that a new daemon could not be connected to, the guide attributes it to network address translation (NAT) masquerading local connections as external ones, which Gradle refuses as a security precaution; the fix is in the network configuration, and the daemon log shows the detected network setup (not run here). Directories, log levels and the log format are in Directories & Logging.

Source: Gradle: Attaching a debugger to your build, Adding and changing logging and Troubleshooting daemon connection issues

Many rare IDE errors disappear when the IDE re-imports the build: in IntelliJ IDEA open the Gradle tool window and use the Refresh icon (the project must be linked to Gradle); in Eclipse with Buildship use the Refresh action of the "Gradle Tasks" view or the Gradle > Refresh Gradle Project command (both not run here). The IDE runs the same Gradle with the same wrapper, so a build that works on the command line and fails in the IDE usually differs in the JDK used for Gradle, in a Gradle User Home, or in the run configuration; see CI & IDE Integration and Init Scripts & the Tooling API.

Source: Gradle: Debugging IDE integration