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.

Introduction & Quick Summary
Symptom. A build that worked yesterday fails on a fresh machine or a new CI runner:
[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 supportedOlder 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:
mvn -v # reads "Java version:" and "runtime:"
export JAVA_HOME=/opt/jdk-25
mvn -v
mvn clean verifyOr lower the release when the code does not use newer APIs:
<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:
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# 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:
<!-- 1. a property, usually the simplest -->
<properties>
<maven.compiler.release>25</maven.compiler.release>
</properties><!-- 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><!-- 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 value | Minimum JDK for javac | Class file major version | Runtime needs |
|---|---|---|---|
| 17 | 17 | 61 | Java 17+ |
| 21 | 21 | 65 | Java 21+ |
| 25 | 25 | 69 | Java 25+ |
| 26 | 26 | 70 | Java 26+ |
| Where the JDK is selected | Tool that reads it | Typical failure |
|---|---|---|
JAVA_HOME | mvn, gradle wrapper | release not supported |
PATH only | java, not the compiler | mvn -v shows a different version |
~/.m2/toolchains.xml | toolchain-aware plugins | no matching toolchain found |
| IDE runner JRE | Maven runs inside the IDE | works in IDE, fails in terminal |
| Docker base image | everything in the stage | works locally, fails in the image |
CI setup-java matrix | the job | one 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:
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:
<!-- ~/.m2/toolchains.xml -->
<toolchains>
<toolchain>
<type>jdk</type>
<provides><version>25</version></provides>
<configuration><jdkHome>/opt/jdk-25</jdkHome></configuration>
</toolchain>
</toolchains><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:
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 /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:
<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:
mvn -v # compiler JDK
"$JAVA_HOME/bin/javac" -version
grep -n "maven.compiler.release\|<release>\|java.version" pom.xml
java -version # runtime JRECommon Compilation/Runtime Mistakes & Version Gotchas
- Checking
java -versioninstead ofmvn -v. Maven usesJAVA_HOME. - Setting
JAVA_HOMEto a JRE. The compiler is absent, and the error is different. - Bumping
maven.compiler.releasewithout bumping the build image. Works locally, fails in Docker. - Assuming
source/targetis equivalent torelease. 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.releasein 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 documentationThe Java documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesSpring Boot: Failed to configure a DataSource and no url attribute
The application never reached the database. The URL is missing, in the wrong file, or under a profile that is not active.
Spring Boot 4: NoClassDefFoundError javax/servlet/http/HttpServlet
Spring Boot 4 runs Jakarta only. A library compiled against javax asks for a class that no longer exists, and the stack trace hides which jar.
ClassNotFoundException vs NoClassDefFoundError in Java
One is a missing lookup, the other a failed link or initialiser. The distinction decides whether you inspect a classpath or a stack trace.
Java: java.lang.OutOfMemoryError: Metaspace
Class metadata lives outside the heap. Which limit was hit, how to find the classloader that grows, and why a container restart with exit code 137 is the same disease.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.