release version not supportedの直し方｜Maven

error: release version 21 not supported は、「Java 21 向けにコンパイルして」と指定したのに、コンパイルに使っている JDK が 21 より前の版のときのエラーです。 pom.xml の指定ではなく、Maven が実際に使っている JDK が原因です。

mvn -v          # 「Java version:」の行が、Maven が使っている JDK

Apache Maven 3.9.11
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64   ← 17 で動いている

直し方は「その版以降の JDK で Maven を動かす」です。JAVA_HOME を JDK 21 に向けると、同じ pom.xml で BUILD SUCCESS になりました。

確認環境：Ubuntu 24.04、Apache Maven 3.9.11、maven-compiler-plugin 3.10.1、Gradle 8.14.3、JDK 8・11・17・21・25（確認日 2026年10月10日）。

再現：同じ pom.xml を JDK を変えてコンパイル

<properties>
  <maven.compiler.release>21</maven.compiler.release>
</properties>

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.10.1:compile
  (default-cli) on project rel: Fatal error compiling: error: release version 21 not supported -> [Help 1]

「新しい JDK で、以前の版向けにコンパイルする」はできますが、「以前の JDK で、新しい版向けにコンパイルする」はできません。 公式ドキュメントでも、release に指定できるのは「使っている JDK の版と、それより前のいくつかの版」とされています。

いちばん多い原因：PATH の java と、Maven が使う JDK が違う

$ java -version
openjdk version "21.0.10" 2026-01-20          ← ターミナルの java は 21

$ mvn -v
Java version: 17.0.20.1, ... runtime: /usr/lib/jvm/java-17-openjdk-amd64   ← Maven は 17

Maven は JAVA_HOME の JDK を使います。 java -version が 21 でも、JAVA_HOME が 17 を指していれば、Maven は 17 でコンパイルします。確認環境でも、この状態で release version 21 not supported になりました。

設定したら、mvn -v の「Java version」が 21 になったことを確かめます。

release・source・target の違い

release を使うのがおすすめです。source・target だけだと、指定した版に無い API（新しい JDK にだけあるメソッド）を使っていても、コンパイルは通ってしまいます。公式ドキュメントでも、--release なら指定した版に無い API の使用をエラーとして検出できるとされています。

JDK 8 で release を使うと invalid flag: --release になります（JDK 8 の javac には --release が無いため）。公式ドキュメントでは、maven-compiler-plugin 3.13.0 以降なら、JDK 8 では release を source・target に読み替えるとされています。

IDE・CI で起きるとき

IDE や CI は、ターミナルとは別の JDK を使っていることがあります。

Gradle の場合：toolchain で JDK を指定する

Gradle で options.release を指定し、JDK 17 で動かすと、同じエラーになりました。

Execution failed for task ':compileJava'.
> Java compilation initialization error
    error: release version 21 not supported

Gradle は toolchain を書くと、Gradle を動かしている JDK とは別に、コンパイル用の JDK を選びます。

// build.gradle.kts
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

確認環境では、Gradle を JDK 17 で動かしたまま、インストール済みの JDK 21（/usr/lib/jvm/java-21-openjdk-amd64）が自動で選ばれ、コンパイルが通りました。指定した版の JDK がどこにも無いときは、次のエラーになりました。

> Cannot find a Java installation on your machine (Linux ... amd64) matching: {languageVersion=22, ...}.
  Toolchain download repositories have not been configured.

Gradle 自体が新しい JDK に対応していないとき

コンパイルの版とは別に、Gradle を動かす JDK が、その Gradle の対応範囲より新しいと、ビルドが始まる前に失敗します。確認環境では、Gradle 8.14.3 を JDK 25 で動かすと、What went wrong: の下に 25.0.4.1 とだけ表示されて失敗しました。Gradle 公式の互換表では、Java 25 で Gradle を動かすには 9.1.0 以降が必要です。

実行時のエラーとの違い

コンパイルは JDK 21 で通っても、実行するサーバーの Java が 17 なら、実行時に UnsupportedClassVersionError になります。release は、実行する環境の Java の版に合わせます。

確認の手順（チェックリスト）

よくある質問

Q. JDK 21 をインストールしたのに直りません。 A. インストールしただけでは、JAVA_HOME は以前の JDK のままのことがあります。mvn -v で、Maven が使っている JDK を確かめます。

Q. release を 17 に下げてもよいですか。 A. 実行する環境が Java 17 で、Java 21 の機能を使っていないなら、17 に合わせるのは正しい直し方です。Java 21 の機能（仮想スレッドなど）を使っているなら、コンパイルでエラーになります。

まとめ

• 指定した版より前の JDK でコンパイルしているのが原因。mvn -v の「Java version」を見る
• Maven は JAVA_HOME の JDK を使う。java -version と違うことがある
• release を使う。source・target は、指定した版に無い API の使用を検出しない
• JDK 8 では invalid flag: --release（maven-compiler-plugin 3.13.0 以降は読み替える）
• Gradle は toolchain で、コンパイル用の JDK を自動で選べる
• 実行時の UnsupportedClassVersionError とは別。release は実行する環境の版に合わせる

参考・出典

確認日はいずれも 2026年10月10日です。

• Apache Maven Compiler Plugin「Setting the --release of the Java Compiler」：https://maven.apache.org/plugins/maven-compiler-plugin/examples/set-compiler-release.html
• Gradle User Manual「Compatibility Matrix」：https://docs.gradle.org/current/userguide/compatibility.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。