javac "error: release version X not supported" in CI - Fix JDK

javac understands the --release flag but not the version you asked for, because that version is newer than the JDK itself. A JDK 17 compiler cannot honor --release 21 - it has no knowledge of release 21.

What this error means

Compilation fails with error: release version 21 not supported. The number is what the build requests; the compiling JDK is older than it (the flag is valid, the version is out of range).

gradle output

> Task :app:compileJava FAILED
error: release version 21 not supported
# build requests --release 21 but javac is JDK 17

Common causes

Requested release newer than the compile JDK

A --release 21 (or maven.compiler.release/sourceCompatibility 21) needs a JDK 21+ compiler. An older JDK supports --release but not that specific version.

CI provisioned an older JDK than the project targets

setup-java pinned (or defaulted to) a JDK below the requested release, so the version is out of the compiler’s supported range.

How to fix it

Provision a JDK at least as new as the release

The compile JDK must be >= the requested release. Pin it in CI.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'   # >= the requested --release

Or lower the requested release

If you cannot upgrade the JDK, request a release the JDK supports.

pom.xml / build.gradle.kts

# Maven
<maven.compiler.release>17</maven.compiler.release>
# Gradle
# java { toolchain { languageVersion = JavaLanguageVersion.of(17) } }

How to prevent it

Keep the requested --release aligned with the provisioned JDK.
Use a Java toolchain so the compile JDK matches the target version.
Assert javac -version against the requested release in CI.