Gradle "Unsupported Java. This version only supports Java up to X" - Fix in CI

By Kaveh Alemi·Latchkey

Gradle refused to run because the JDK launching it is newer than that Gradle version can support. Each Gradle release caps the JVM it runs on; a too-new runner JDK trips that cap.

What this error means

The build aborts immediately with Unsupported Java. ... This version of Gradle only supports Java up to version 17. You are using Java 21. No tasks execute.

gradle

FAILURE: Build failed with an exception.

* What went wrong:
Could not open cp_init generic class cache ...
> Unsupported Java. Your build is currently configured to use Java 21.
  This version of Gradle only supports Java up to version 17.

Common causes

Gradle wrapper older than the runner JDK

A pinned old wrapper meets a runner that provisioned a newer default JDK.

JAVA_HOME bumped without bumping Gradle

CI now sets JAVA_HOME to JDK 21 but the wrapper version still caps at 17.

Compile JDK conflated with Gradle JDK

Using one JDK for both running Gradle and compiling forces Gradle onto an unsupported JVM.

How to fix it

Upgrade the wrapper to a version that supports the JDK

Bump Gradle so it can run on the runner JDK.

Terminal

./gradlew wrapper --gradle-version 8.10

Run Gradle on a supported JDK, compile with toolchains

Decouple the Gradle JVM from the compile JVM.

properties

# gradle.properties
org.gradle.java.home=/usr/lib/jvm/temurin-17

Pin the launch JDK in the CI step

Select a Gradle-compatible JDK before invoking the wrapper.

yaml

- uses: actions/setup-java@v4
  with: { distribution: temurin, java-version: 17 }

How to prevent it

Bump the Gradle wrapper before raising the runner JDK.
Use Java toolchains so compile JDK is independent of Gradle JDK.
Pin the launch JDK in CI rather than relying on the runner default.

Frequently asked questions

What causes ""this version only supports Java up to X""?