How to configure Gradle to use Java 17

Gradle is an open-source build automation tool and project management system that is widely used for building, testing, and deploying software projects. In this tutorial we will learn how to configure it to use Java 17 and how to solve common issues with it.

Gradle provides a flexible and powerful way to automate the build process, manage dependencies, and perform various tasks related to software development. Gradle uses a Groovy-based domain-specific language (DSL) or Kotlin for scripting build configurations, making it highly customizable and adaptable to different project needs.

Configuring Gradle to use Java 17 is a trivial task however there are some pitfalls in case you have different environment settings in your shell or in your Development environment (namely in IntelliJ Idea).

Let’s get through the basic Java settings in the build.gradle file and then we will troubleshoot most common issues.

Configuring Java in Gradle

To configure Java 17 in Gradle you can add in your build.gradle the following configuration:

sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17

Here is an explanation to the above settings:

  1. sourceCompatibility:
    • This setting specifies the version of the Java language features that your source code will use. In other words, it determines which Java language features you are allowed to use in your code.
    • The value JavaVersion.VERSION_17 indicates that you are configuring your project to use Java 17 language features.
    • If you write code that uses language features introduced in Java 17, you can set the sourceCompatibility to this version. However, keep in mind that your code might not be compatible with older JDKs if they do not support the new features.
  2. targetCompatibility:
    • This setting specifies the version of the Java bytecode that your compiled classes will be compatible with.
    • The value JavaVersion.VERSION_17 means that your compiled classes will be compatible with the Java 17 bytecode format.
    • When you set targetCompatibility to a certain version, it ensures that your compiled code produces bytecode that is compatible with that version of the Java Runtime Environment (JRE). This means that your code can run on a JRE that is at least the version you’ve specified.

Difference Between sourceCompatibility and targetCompatibility:

  • sourceCompatibility determines the Java language features you can use in your source code. It specifies the version of the language your code is written in.
  • targetCompatibility determines the version of the Java bytecode that your compiled classes will be compatible with. It specifies the minimum version of the JRE that can run your compiled code.

In general, it’s a good practice to set both sourceCompatibility and targetCompatibility to the same version if you’re using a specific version of the Java language. This ensures that the code you write uses the features available in that version and produces bytecode that’s compatible with the same version of the JRE.

However, there might be cases where you need to set a lower targetCompatibility than your sourceCompatibility. For example, you might want to compile your code using the latest language features (sourceCompatibility) but still produce bytecode that’s compatible with an older JRE (targetCompatibility) to ensure broader compatibility with different runtime environments.

To see the full list of Java Enums, you can refer to this page:

Troubleshooting common errors

One common error can happen if you have a misconfiguration between build.gradle and the JDK in your Development Environment. This can result in the following error:

Cause: error: invalid source release: 17

The most common cause of this issue is a wrong Gradle Build Configuration. When using IntelliJ Idea check the Settings | Build, Execution,Deployment | Build Tools | Gradle and verify the Gradle JVM setting:

Cause: error: invalid source release: 17

Make sure that you are using a Java 17 SDK in it.

Besides, verify that the JAVA_HOME of your IDE is also Java 17:

On a Linux Machine:

export JAVA_HOME=/path/to/openjdk-17

On Windows:

set JAVA_HOME=path\to\openjdk-17

Finally, remember that after making changes to the build.gradle file, you’ll need to sync your Gradle project to apply the configuration changes. This can be done through your IDE or by using the command-line:

For IntelliJ IDEA:

  1. Click on “File” in the top menu.
  2. Select “Sync Project with Gradle Files.”

On the command line, you can run:

./gradlew clean build


Congratulations! You’ve successfully configured the JDK version in your Gradle project. Keep in mind that the steps might vary slightly depending on your specific project structure and needs. Always make sure to replace the example JDK version with the version you want to use.

Remember that the JDK version configuration is just one aspect of your Gradle setup. Depending on your project’s requirements, you might need to configure other settings as well, such as dependencies, repositories, and plugins.

If you want to learn more about using Gradle with WildFly, check this article: Gradle tutorial for WildFly users