# Troubleshooting builds

version 9.0.0

The following is a collection of common issues and suggestions for addressing them. You can get other tips and search the Gradle forums and StackOverflow #gradle answers.

## Troubleshooting the installation

If you followed the installation instructions, and aren’t able to execute your Gradle build, here are some tips that may help.

If you installed Gradle outside of just invoking the Gradle Wrapper, you can check your Gradle installation by running `gradle --version` in a terminal.

You should see something like this:

    ❯ gradle --version

    ------------------------------------------------------------
    Gradle {gradleVersion}
    ------------------------------------------------------------

    Build time:    2025-05-13 06:56:13 UTC
    Revision:      3c890746756262d3778e12eaa5155d661d7cbdf2

    Kotlin:        2.1.21
    Groovy:        4.0.27
    Ant:           Apache Ant(TM) version 1.10.15 compiled on August 25 2024
    Launcher JVM:  22.0.1 (Oracle Corporation 22.0.1+8-16)
    Daemon JVM:    Compatible with Java 17, any vendor, nativeImageCapable=false (from gradle/gradle-daemon-jvm.properties)
    OS:            Mac OS X 15.5 aarch64

If not, here are some things you might see instead.

### Command not found: gradle

If you get "command not found: gradle", you must ensure that Gradle is correctly added to your `PATH`.

### JAVA_HOME is set to an invalid directory

If you get an error like:

    ERROR: JAVA_HOME is set to an invalid directory

Set the JAVA_HOME variable in your environment to match the location of your Java installation:

    $ export JAVA_HOME=/Users/user/Library/Java/JavaVirtualMachines/corretto-22.0.1/Contents/Home
    $ echo $JAVA_HOME
    /Users/user/Library/Java/JavaVirtualMachines/corretto-22.0.1/Contents/Home

You must ensure that a Java Development Kit version 17 or higher is properly installed, the `JAVA_HOME` environment variable is set, and Java is added to your `PATH`.

### Permission denied

If you get "permission denied", that means that Gradle likely exists in the correct place, but it is not executable. You can fix this using `chmod +x path/to/executable` on *nix-based systems.

### Other installation failures

If `gradle —-version` works, but all of your builds fail with the same error, it is possible that one of your Gradle build configuration scripts is broken.

You can verify the problem with Gradle scripts by running `gradle help`, which executes configuration scripts but no Gradle tasks. If the error persists, it means the build configuration is problematic. If not, the problem exists when executing one or more requested tasks (Gradle executes configuration scripts first, followed by build steps).

## Debugging dependency resolution

Common dependency resolution issues, such as resolving version conflicts, are covered in Troubleshooting Dependency Resolution.

You can see a dependency tree and see which resolved dependency versions differed from what was requested by clicking the Dependencies view and using the search functionality, specifying the resolution reason.

Figure 1. Debugging dependency conflicts with Build Scan

The actual Build Scan with filtering criteria is available for exploration.

## Troubleshooting slow builds

For build performance issues (including "slow sync time"), see improving the Performance of Gradle Builds.

Android developers should watch a presentation by the Android SDK Tools team about Speeding Up Your Android Gradle Builds. Many tips are also covered in the Android Studio user guide on optimizing build speed.

## Debugging build logic

### Attaching a debugger to your build

You can set breakpoints and debug `buildSrc` and standalone plugins in your Gradle build itself by setting the `org.gradle.debug` property to "true" and then attaching a remote debugger to port 5005. You can change the port number by setting the `org.gradle.debug.port` property to the desired port number.

To attach the debugger remotely via the network, you must set the `org.gradle.debug.host` property to the machine’s IP address or `*` (listen on all interfaces).

    ❯ gradle help -Dorg.gradle.debug=true

Using the Kotlin DSL, you can debug the build scripts themselves.

The following video demonstrates how to debug an example build using IntelliJ IDEA.

Figure 2. Interactive debugging of a build script

### Adding and changing logging

In addition to controlling logging verbosity, you can also control display of task outcomes (e.g. "UP-TO-DATE") in lifecycle logging using the `--console=verbose` flag.

You can also replace much of Gradle’s logging with your own by registering various event listeners. One example of a custom event logger is explained in the logging documentation. You can also control logging from external tools, making them more verbose to debug their execution.

| Additional logs from the Gradle Daemon can be found under `$GRADLE_USER_HOME/daemon/9.0.0/`.

### Task executed when it should have been UP-TO-DATE

`--info` logs explain why a task was executed, though a Build Scan does this in a searchable, visual way by going to the Timeline view and clicking on the task you want to inspect.

Figure 3. Debugging incremental build with Build Scan

You can learn what the task outcomes mean from this listing.

## Debugging IDE integration

Many infrequent errors within IDEs can be solved by "refreshing" Gradle. See also more documentation on working with Gradle in IntelliJ IDEA and in Eclipse.

### Refreshing IntelliJ IDEA

| This only works for Gradle projects linked to IntelliJ.

From the main menu, go to `View` > `Tool Windows` > `Gradle`. Then click on the Refresh icon.

Figure 4. Refreshing a Gradle project in IntelliJ IDEA

### Refreshing Eclipse (using Buildship)

If you’re using Buildship for the Eclipse IDE, you can re-synchronize your Gradle build by opening the "Gradle Tasks" view and clicking the "Refresh" icon, or by executing the `Gradle` > `Refresh Gradle Project` command from the context menu while editing a Gradle script.

Figure 5. Refreshing a Gradle project in Eclipse Buildship

### Troubleshooting daemon connection issues

If your Gradle build fails before running any tasks, you may be encountering network configuration problems. When Gradle is unable to communicate with the Gradle daemon process, the build will immediately fail with a message similar to this:

    $ gradle help

    Starting a Gradle Daemon, 1 stopped Daemon could not be reused, use --status for details

    FAILURE: Build failed with an exception.

    * What went wrong:
    A new daemon was started but could not be connected to: pid=DaemonInfo{pid=55913, address=[7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[/127.0.0.1]], state=Busy, ...

This can occur when network address translation (NAT) masquerade is used. When NAT masquerade is enabled, connections that should be considered local to the machine are masked to appear from external IP addresses. Gradle refuses to connect to any external IP address as a security precaution.

The solution to this problem is to adjust your network configuration such that local connections are not modified to appear as from external addresses.

You can monitor the detected network setup and the connection requests in the daemon log file (`$GRADLE_USER_HOME/daemon/<Gradle version>/daemon-<PID>.out.log`).

    2021-08-12T12:01:50.755+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding IP addresses for network interface enp0s3
    2021-08-12T12:01:50.759+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Is this a loopback interface? false
    2021-08-12T12:01:50.769+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding remote address /fe80:0:0:0:85ba:3f3e:1b88:c0e1%enp0s3
    2021-08-12T12:01:50.770+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding remote address /10.0.2.15
    2021-08-12T12:01:50.770+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding IP addresses for network interface lo
    2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Is this a loopback interface? true
    2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding loopback address /0:0:0:0:0:0:0:1%lo
    2021-08-12T12:01:50.771+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.InetAddresses] Adding loopback address /127.0.0.1
    2021-08-12T12:01:50.775+0200 [DEBUG] [org.gradle.internal.remote.internal.inet.TcpIncomingConnector] Listening on [7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[localhost/127.0.0.1]].
    ...
    2021-08-12T12:01:50.797+0200 [INFO] [org.gradle.launcher.daemon.server.DaemonRegistryUpdater] Advertising the daemon address to the clients: [7fb34c82-1907-4c32-afda-888c9b6e2279 port:42751, addresses:[localhost/127.0.0.1]]
    ...
    2021-08-12T12:01:50.923+0200 [ERROR] [org.gradle.internal.remote.internal.inet.TcpIncomingConnector] Cannot accept connection from remote address /10.0.2.15.

## Getting additional help

If you didn’t find a fix for your issue here, please reach out to the Gradle community on the help forum or search relevant developer resources using help.gradle.org.

If you believe you’ve found a bug in Gradle, please file an issue on GitHub.