Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Maven: release version 25 not supported and where the JDK comes from

Six places choose the JDK and only one matters per build. Diagnose the release error, then pin the compiler so it cannot drift again.

~4 min readJava
#Java#Maven#JDK#CI
Two JDK crates of different heights with an amber mismatch plate between them and a compiler gate

Introduction & Quick Summary

Symptom. A build that worked yesterday fails on a fresh machine or a new CI runner:

code
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project api: Fatal error compiling: error: release version 25 not supported

Older setups phrase it as invalid target release: 25, and IntelliJ reports invalid source release: 21. Nothing in pom.xml changed, which is the clue: the JDK that runs the compiler changed.

Cause. javac can only target releases it knows about. <maven.compiler.release>25</maven.compiler.release> asks for a Java 25 API surface, and a JDK 21 compiler has no data for it, so it refuses. Maven runs the compiler from JAVA_HOME, not from the java on your PATH, so a machine can show Java 25 in a terminal and still build with a JDK 21 in JAVA_HOME. A JAVA_HOME pointing at a JRE has the same effect from the other direction: there is no compiler at all.

Fix. Point the build at a JDK that is at least as new as the release:

bash
mvn -v # reads "Java version:" and "runtime:" export JAVA_HOME=/opt/jdk-25 mvn -v mvn clean verify

Or lower the release when the code does not use newer APIs:

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

The rest of this guide is about which of the many places the JDK is chosen wins, how to pin it per project with toolchains, and how the same mistake appears in Docker and CI.

Core Mechanics, Signatures & Reproducible Setup

--release N compiles against the API of Java N and emits class files for Java N. It replaced -source/-target, which could compile against the current JDK's API while claiming an older target, a combination that produced code that failed at runtime. Maven maps maven.compiler.release to --release, and the value must be understood by the JDK that executes javac.

Reproduce the mismatch deterministically, with two JDKs installed:

bash
ls /usr/lib/jvm mvn -v | sed -n '/Java version/p;/runtime/p' JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64 mvn -q compile # Fatal error compiling: error: release version 25 not supported JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64 mvn -q compile # BUILD SUCCESS
bash
# what the compiler supports, from the JDK you are pointing at "$JAVA_HOME/bin/javac" --help | sed -n '/--release/,/^$/p'

The supported-release list is the authoritative answer to "can this JDK build my project". A JDK 25 prints releases up to 25; a JDK 21 stops at 21.

Where the release value can come from, in the order Maven resolves it:

xml
<!-- 1. a property, usually the simplest --> <properties> <maven.compiler.release>25</maven.compiler.release> </properties>
xml
<!-- 2. plugin configuration, which wins over the property --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.14.0</version> <configuration> <release>25</release> </configuration> </plugin>
xml
<!-- 3. the Spring Boot parent, which sets java.version --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>4.0.0</version> </parent> <properties> <java.version>25</java.version> </properties>

A command-line -Dmaven.compiler.release=21 overrides all three for one run, which is the fastest way to test whether the code really needs the newer API.

Key Comparison Table

Release valueMinimum JDK for javacClass file major versionRuntime needs
171761Java 17+
212165Java 21+
252569Java 25+
262670Java 26+
Where the JDK is selectedTool that reads itTypical failure
JAVA_HOMEmvn, gradle wrapperrelease not supported
PATH onlyjava, not the compilermvn -v shows a different version
~/.m2/toolchains.xmltoolchain-aware pluginsno matching toolchain found
IDE runner JREMaven runs inside the IDEworks in IDE, fails in terminal
Docker base imageeverything in the stageworks locally, fails in the image
CI setup-java matrixthe jobone matrix entry fails

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. JAVA_HOME points at a JRE

A JRE has a java binary and no javac, so the error becomes No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?. Installing the JDK package and fixing the path is the whole fix:

bash
readlink -f "$JAVA_HOME" ls "$JAVA_HOME/bin/javac" || echo "this is a JRE"

On macOS, /usr/libexec/java_home -V lists installed JDKs and prints the exact path to export.

2. Toolchains: pin the JDK per project

When the build server must stay on an older JDK for other projects, Maven toolchains select a different JDK for the compiler, Surefire and Javadoc without touching JAVA_HOME:

xml
<!-- ~/.m2/toolchains.xml --> <toolchains> <toolchain> <type>jdk</type> <provides><version>25</version></provides> <configuration><jdkHome>/opt/jdk-25</jdkHome></configuration> </toolchain> </toolchains>
xml
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-toolchains-plugin</artifactId> <version>3.2.0</version> <executions> <execution> <goals><goal>toolchain</goal></goals> </execution> </executions> <configuration> <toolchains> <jdk><version>25</version></jdk> </toolchains> </configuration> </plugin>

A missing toolchain fails with Cannot find matching toolchain definitions, which is more honest than a release error because it names the requirement.

3. Docker: the base image decides

A maven:3.9-eclipse-temurin-21 image runs javac 21 regardless of the pom.xml, so a release bump alone breaks the image build:

dockerfile
FROM maven:3.9-eclipse-temurin-25 AS build WORKDIR /src COPY pom.xml . RUN mvn -B -q dependency:go-offline COPY src ./src RUN mvn -B -q -DskipTests package FROM eclipse-temurin:25-jre COPY --from=build /src/target/*.jar /app/app.jar ENTRYPOINT ["java", "-jar", "/app/app.jar"]

The runtime stage matters too: class files for release 25 will not run on a 21 JRE, and the error there is UnsupportedClassVersionError: class file version 69.0.

4. CI matrices that mix versions

A matrix that builds several JDKs against one release value fails on every entry older than the release. Either derive the release per entry, or drop the entries that cannot compile:

- uses: actions/setup-java@v4 with: distribution: temurin java-version: ${{ matrix.java }} - run: mvn -B verify -Dmaven.compiler.release=${{ matrix.java }}

Sorting this out in CI is usually the moment a team decides the minimum JDK the project supports, which is worth writing into the README.

5. Preview features and --enable-preview

A preview feature needs --release N plus --enable-preview, and the compiler must be exactly JDK N. Mixing a newer JDK with an older release, or forgetting the flag, produces preview features are not supported in -source 21:

xml
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.14.0</version> <configuration> <release>25</release> <compilerArgs><arg>--enable-preview</arg></compilerArgs> </configuration> </plugin>

At runtime the same classes need java --enable-preview, so preview code should not ship in a release build without a deliberate decision.

6. Reading the failure to the right layer

release version not supported is a compile-time mismatch. UnsupportedClassVersionError is a runtime mismatch, usually a newer build on an older JRE. invalid target release is the pre---release wording. Three different layers, three different fixes:

bash
mvn -v # compiler JDK "$JAVA_HOME/bin/javac" -version grep -n "maven.compiler.release\|<release>\|java.version" pom.xml java -version # runtime JRE

Common Compilation/Runtime Mistakes & Version Gotchas

  • Checking java -version instead of mvn -v. Maven uses JAVA_HOME.
  • Setting JAVA_HOME to a JRE. The compiler is absent, and the error is different.
  • Bumping maven.compiler.release without bumping the build image. Works locally, fails in Docker.
  • Assuming source/target is equivalent to release. It does not check the API surface.
  • Forgetting the runtime image when raising the release. Class files fail later with a version error.
  • Editing the IDE's project SDK and expecting the CLI to change. They are separate settings.
  • Leaving maven.compiler.release in a parent POM. Child modules inherit a release their build JDK may not support.
  • Using preview features in a library. Consumers need the same flag and the exact JDK.

Keep JAVA_HOME and the other build variables readable with the environment file inspector, and compare the parent and child POM effectively with the text diff tool when a property seems to be ignored.

Reference: setting the compiler release, the javac manual, and the Maven toolchains guide.

Official references

primary documentation

The Java documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.