Gradle "requires Java X" / Unsupported JDK - Fix in CI

The JDK running Gradle is outside the range this Gradle version supports - too old to launch, or newer than the version handles. Gradle and its runtime JDK must be a compatible pair.

What this error means

Gradle fails at startup with a message that it requires a particular Java version, or that the current JDK is unsupported - before any of your build logic runs.

gradle output

FAILURE: Build failed with an exception.
* What went wrong:
Could not create service of type ... using BuildScopeServices.
> Gradle 8.8 requires Java 8 or later to run. You are currently using Java 7.

Common causes

Runtime JDK below Gradle’s minimum

Each Gradle release sets a minimum JDK to run on. An older JDK on the runner cannot launch a newer Gradle.

Gradle too old for a newer JDK

The reverse: an old Gradle run on a much newer JDK is unsupported and may fail to start or crash during configuration.

How to fix it

Run Gradle on a supported JDK

Provision a JDK within the Gradle version’s supported range for the Gradle-runtime process.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '17'   # JDK that launches this Gradle
- run: ./gradlew --version

Upgrade the Gradle wrapper to match the JDK

Bump the wrapper to a version that supports the JDK your CI provisions.

Terminal

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

How to prevent it

Keep the Gradle wrapper version aligned with the JDKs CI provisions.
Use Java toolchains to decouple the compile JDK from the Gradle-runtime JDK.
Assert ./gradlew --version and java -version early in CI.