Gradle Version Incompatible With Java Version - Fix in CI

The JDK launching Gradle is outside the range this Gradle version supports. Each Gradle release supports a known JDK window; running it on a JDK that is too new (or too old) is rejected up front.

What this error means

Gradle fails at startup with a message that it requires a specific Java range, or that the current JVM is unsupported, before any of your build logic runs.

gradle output

FAILURE: Build failed with an exception.
* What went wrong:
Gradle 7.4 requires Java 8, 11, or 17 to run. You are currently using Java 21.
   Please use a compatible version of Java to run Gradle.

Common causes

Gradle too old for the runner JDK

CI provisioned a newer JDK than the pinned Gradle version supports for its own runtime, so Gradle refuses to start.

JAVA_HOME points at an unsupported JDK

Even with a compatible Gradle available, JAVA_HOME selecting a JDK outside the supported window makes Gradle reject the JVM.

How to fix it

Upgrade the Gradle wrapper

Bump the wrapper to a version whose supported JDK window includes the runner JDK.

Terminal

./gradlew wrapper --gradle-version 8.8
# commit gradle/wrapper/gradle-wrapper.properties

Run Gradle on a supported JDK, compile via toolchain

Launch Gradle on a JDK it supports, and select your compile JDK independently with a toolchain.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '17'   # JDK that runs Gradle
# build.gradle.kts: java { toolchain { languageVersion = JavaLanguageVersion.of(21) } }

How to prevent it

Keep the Gradle wrapper current with the JDKs CI provisions, and decouple the Gradle-runtime JDK from the compile JDK using Java toolchains.