skip to content

Before upgrading the JDK on your CI agents or bumping Gradle, how do you use the official Gradle compatibility matrix to avoid breakage?

level: middleimportance: must knowfreq 55%

answer

  1. official matrix = run-on + toolchain rows
  2. run-on support lands before toolchain support
  3. JDK 17→7.3, JDK 21→8.5
  4. ./gradlew --version prints the JVM
  5. classify: CI JDK vs Gradle vs target

basics

~10 s

Look up your Gradle version in the official compatibility matrix to confirm it supports running on the target JDK before installing that JDK on CI. If not, bump Gradle first.

solid answer

~50 s

Gradle publishes a **Java compatibility matrix** that maps each Gradle version to the JDK versions it can *run on* (and notes toolchain/compile support separately). The workflow before an upgrade: (1) decide whether you're changing the JDK that runs Gradle, the Gradle version, or the project's target Java; (2) for a CI JDK bump, find the lowest Gradle version that supports running on that JDK — e.g. JDK 21 needs Gradle 8.5+, JDK 24+ needs even newer — and ensure your wrapper meets it; (3) for a Gradle bump, check it still supports the JDK your agents have. Order matters: support for *running* on a new JDK lands before *toolchain* support for compiling against it, so you may run Gradle on an older JDK while a toolchain provides the new one. Verify the daemon JDK with `./gradlew --version` (it prints the JVM) and treat the matrix as the source of truth, not trial-and-error.

code

bash · 5 lines
bash
# Confirm which JVM the Gradle daemon is actually running on,
# then check that JVM against the official compatibility matrix.
./gradlew --version
#   Gradle 8.7
#   JVM:  21.0.2 (Eclipse Adoptium 21.0.2+13)  <-- must be in 8.7's run-on range

go deeper

for a junior

Know that an official matrix exists and you check it before upgrading.

for a middle

Walk through classifying the change and finding the minimum Gradle for a JDK.

for a senior

Explain run-on vs toolchain timing and verifying with --version on CI.

for a principal

Define an upgrade policy: matrix-gated bumps, staged rollout, pinned daemon JDK across the org.

## The compatibility matrix as a gate Gradle maintains an official **Compatibility Matrix** (in the docs and the "Compatibility" page) that answers two questions per Gradle release: 1. **Which JDKs can run this Gradle version?** (the daemon's JVM) 2. **Which Java versions can it compile/test against via toolchains?** These land at different times: Gradle typically gains the ability to *run on* a new JDK before it can *target* that JDK as a toolchain language version. ### A safe upgrade procedure **Step 1 — classify the change.** Are you (a) putting a newer JDK on CI that launches Gradle, (b) bumping the Gradle version, or (c) raising the project's target Java? Each touches a different row/column of the matrix. **Step 2 — for a CI/runner JDK bump.** Find the minimum Gradle version that supports *running on* that JDK. Rough landmarks: JDK 17 → Gradle 7.3+, JDK 21 → Gradle 8.5+, newer JDKs require progressively newer Gradle. If your wrapper is older, bump the wrapper first (or keep the old daemon JDK and use a toolchain for the new compile target). **Step 3 — for a Gradle bump.** Confirm the new Gradle still supports your existing agents' JDK in its run-on range (Gradle drops very old JDKs over time). **Step 4 — verify reality.** Run: ```bash ./gradlew --version ``` It prints the Gradle version *and* the JVM it is running on. Cross-check that JVM against the matrix. ### Why not just try it Running Gradle on an unsupported JDK can fail loudly (`Unsupported class file major version`) or, worse, behave subtly wrong with plugins. The matrix is the authoritative, version-pinned answer; trial-and-error on CI wastes pipeline runs and risks intermittent failures. ### Toolchains as the escape hatch If the matrix says your Gradle can't *run on* a JDK you need to *target*, keep Gradle on a supported JDK and set a toolchain `languageVersion` for the new target — Gradle provisions or locates that JDK just for compilation/tests.

  • Why might 'run on JDK 21' be supported before 'compile to Java 21 via toolchain'?
    Running only needs the daemon JVM to work; toolchain language-version support requires Gradle to understand/emit that bytecode level, which lands in a later release.
  • Your CI installs JDK 24 but the build fails to start. What's the first check?
    Whether your wrapper's Gradle version supports running on JDK 24 in the matrix; if not, bump Gradle or pin the daemon to a supported JDK.

saying these in an interview costs you the question

  • Upgrading the CI JDK without checking the matrix and assuming the existing Gradle will cope.
  • Treating run-on support and toolchain target support as the same row.

context

resolving links…