Maven「release version 25 not supported」の原因と直し方

要約

mvn compile がコンパイルの段階で止まる。
Maven 3.10.0・maven-compiler-plugin 3.16.0・JDK 21 の組み合わせで、pom.xml に Java 25 を指定すると次のように出る。

[INFO] Compiling 1 source file with javac [debug release 25] to target/classes
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.16.0:compile (default-compile) on project demo: Fatal error compiling: error: release version 25 not supported -> [Help 1]

release version 25 not supported は、javac が --release 25 を受け付けなかったというエラーだ。pom.xml の maven.compiler.release は javac の --release に渡される。
そして --release に指定できるのは、使っている JDK 自身のバージョンと、それより前の限られたバージョンだけである（Setting the --release of the Java Compiler（新しいタブで開く）↗）。
JDK 21 の javac は、Java 25 向けのコンパイルができない。
数字は pom.xml に書いた値がそのまま出るので、17 や 21 でも原因は同じだ。

解決策

1. Maven が使っている JDK を確かめる

mvn -v

Apache Maven 3.10.0 (c43a36b8d67be7e0805a411bc0898af1a51f5472)
Maven home: /usr/share/maven
Java version: 21.0.12.1, vendor: Eclipse Adoptium, runtime: /opt/java/openjdk

Java version が Maven の使う JDK だ。release の値より古ければ、2 か 3 で直す。

2. 新しい JDK で Maven を動かす

JDK 25 以上を入れ、JAVA_HOME をそこへ向ける。
切り替わったかは mvn -v で見る。

export JAVA_HOME=/path/to/jdk-25
mvn -v
mvn compile

GitHub Actions では、setup-java の java-version を pom.xml に合わせる。

- uses: actions/setup-java@v6
  with:
    distribution: temurin
    java-version: '25'

3. release を手元の JDK に合わせて下げる

Java 25 の言語機能や API を使っていないなら、release を手元の JDK 以下にする。

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

古い source / target と違い、--release は指定したバージョンに無い標準 API の使用もコンパイル時に弾く。

4. Maven と別の JDK でコンパイルする

Maven は今の JDK で動かしたまま、コンパイルだけ別の JDK で行うなら Toolchains を使う（Guide to Using Toolchains（新しいタブで開く）↗）。

よくある原因

1. JDK が古い。pom.xml には 25 と書いたのに、Maven を動かしている JDK が 21 のままになっている。
   特に設定しなければ、Maven は自分を動かしている JDK の javac でコンパイルする。
2. JAVA_HOME が古い JDK を指している。mvn の起動スクリプトは、JAVA_HOME が設定されていればその JDK の java で Maven を動かす。
   新しい JDK を入れて java -version が新しくなっても、JAVA_HOME が古いままなら Maven は古い JDK で動く。
3. CI の JDK が古い。
   CI だけ落ちるなら、actions/setup-java の java-version などが pom.xml の指定より古い。
4. source / target で書いている。maven.compiler.release ではなく maven.compiler.source と maven.compiler.target に 25 を書いた場合、同じ食い違いは error: invalid target release: 25 として出る。