How to Configure Gradle to Use Java 21, Java 17, and Modern JDKs

Gradle is one of the most popular build automation systems in the Java ecosystem. Configuring the target Java Development Kit (JDK) for a Gradle project is a fundamental task, but mismatches between your local shell, IDE settings (such as IntelliJ IDEA), and build scripts can easily lead to build failures.

1. The Modern Approach: Gradle Java Toolchains (Java 21 & Beyond)

Java Toolchains automatically detect installed JDKs on your system or download the required JDK vendor distribution if it is missing.

Configuring Java 21 via Groovy DSL (build.gradle)

plugins {
    id 'java'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Configuring Java 21 via Kotlin DSL (build.gradle.kts)

plugins {
    java
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}

Why Toolchains Are Superior to Legacy Compatibility Flags:

• Consistent Builds: Every team member and CI/CD pipeline compiles with the exact same JDK version.
• Auto-Provisioning: Gradle can automatically download the specified JDK (e.g., Temurin, Corretto, Azul) if not found locally.
• Complete Alignment: Toolchains configure the compiler, Javadoc generator, and test execution runner simultaneously.

2. Gradle & JDK Compatibility Matrix

Ensure that your Gradle Wrapper version supports the JDK version you intend to target:

To upgrade your Gradle Wrapper version to the latest 8.x release, run:

$ ./gradlew wrapper --gradle-version 8.10.2

3. Legacy Configuration: How to Configure Gradle to Use Java 17

If you are maintaining an existing project that does not use Java Toolchains, you can explicitly configure Java 17 using the legacy sourceCompatibility and targetCompatibility properties.

Java 17 via Groovy DSL (build.gradle)

plugins {
    id 'java'
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Java 17 via Kotlin DSL (build.gradle.kts)

plugins {
    java
}

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

Understanding the Difference:

• sourceCompatibility: Defines the Java language features allowed in your source code (e.g., text blocks, records, sealed classes available in Java 17).
• targetCompatibility: Defines the bytecode target version generated by the Java compiler for the target JRE runtime.

4. Troubleshooting Common Errors

Error 1: Cause: error: invalid source release: 17 (or 21)

This error occurs when Gradle is instructed to compile for Java 17/21, but the underlying JDK running the Gradle build is an older version (such as Java 8 or 11).

Solution in IntelliJ IDEA:

1. Navigate to Settings / Preferences | Build, Execution, Deployment | Build Tools | Gradle.
2. Locate the Gradle JVM dropdown menu.
3. Select a valid JDK matching your target version (e.g., JDK 17 or JDK 21).

Error 2: Overriding Gradle's JDK via gradle.properties

If you want to enforce a specific JDK path without altering global environment variables, define org.gradle.java.home in your project's gradle.properties file:

# For Linux / macOS
org.gradle.java.home=/usr/lib/jvm/java-21-openjdk

# For Windows
org.gradle.java.home=C:/Program Files/Java/jdk-21

Error 3: Setting JAVA_HOME Environment Variable

Verify that your terminal session is using the correct JDK:

Linux / macOS:

$ export JAVA_HOME=/path/to/jdk-21
$ ./gradlew --version

Windows (Command Prompt / PowerShell):

set JAVA_HOME=C:\path\to\jdk-21
.\gradlew.bat --version

5. Frequently Asked Questions (FAQs)

Q1: Should I use Java Toolchains or sourceCompatibility?

Use Java Toolchains. Toolchains are the modern Gradle standard because they guarantee cross-compilation safety and can automatically provision missing JDKs for your team members.

Q2: Can I run Gradle on Java 17 while compiling code for Java 21?

With Java Toolchains, yes. Gradle can run its internal Daemon on JDK 17 while invoking a JDK 21 toolchain compiler to build your application binaries.

Conclusion

Configuring Java versions in Gradle is straightforward when using modern Java Toolchains. By aligning your Gradle Wrapper version, IDE settings, and build scripts, you can seamlessly target Java 21, Java 17, or any future JDK release.