Troubleshooting builds

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

If you get an error like:

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

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

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.

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).

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).

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

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

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.

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

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

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

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.

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:

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).