Maven Error: release version 21/25 not supported [Solved]

The Maven error “release version 25 not supported” (or 21, or 17) means that the JDK running Maven is older than the Java version set in the release option of the maven-compiler-plugin, and we fix it by running Maven on a JDK of that version or newer. A JDK 21 cannot compile for Java 25, because it does not know the Java 25 class file format and APIs.

We see the error right after we raise the Java version in pom.xml, for example from 21 to 25, while JAVA_HOME on our machine, in IntelliJ IDEA or on the CI server still points to the old JDK.

The following example checks which JDK Maven uses and points JAVA_HOME to JDK 25, with the result of each command as a comment.

mvn -v                                    # Java version: 21.0.12.1 -> too old for release 25
export JAVA_HOME=/opt/jdk-25              # Linux and macOS (Windows: set JAVA_HOME=C:\devsetup\JDKs\jdk25)
mvn -v                                    # Java version: 25.0.4.1
mvn clean compile                         # BUILD SUCCESS

Notice that we check the JDK with mvn -v and not with java -version. Maven runs on the JDK in JAVA_HOME, which can differ from the java command on the PATH.

Next, we look at the exact error messages and the version rule behind them. After that, we fix the error in the terminal, in pom.xml, with Maven toolchains, in IntelliJ IDEA and on a CI server.

1. What “release version not supported” Means

The release option tells javac which Java version to compile for, and javac checks our code against the API of that version (JEP 247). A JDK can compile for its own version and for older versions, but never for a newer one, so JDK 21 has no data for Java 25.

The following example is a small project with maven.compiler.release set to 25, compiled by Maven 3.9.11 on JDK 21 with maven-compiler-plugin 3.16.0.

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

The message depends on the option that sets the Java version. Projects that still use source and target instead of release get “invalid target release”, which we cover in a separate article on invalid target release. All four messages come from the same version mismatch.

JDK running Maven	Setting in pom.xml	Error message
21	release 25	error: release version 25 not supported
21	source 25 and target 25	error: invalid target release: 25
21	source 25 and target 21	error: invalid source release: 25
25	release 7	error: release version 7 not supported

The last row is the opposite case. JDK 25 no longer supports Java 7 and older, so a very old release value fails on a new JDK too, as we see in section 5.2.

2. Checking Which JDK Maven Uses

Maven prints its own JDK with mvn -v. The line Java version shows the version, and runtime shows the folder of that JDK.

mvn -v

Apache Maven 3.9.11 (3e54c93a704957b63ee3494413a2b544fd3d825b)
Maven home: /opt/maven
Java version: 21.0.12.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-21-openjdk-amd64
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "6.18.44-fc-v64", arch: "amd64", family: "unix"

Internally, Maven uses the JAVA_HOME environment variable, so the Java version in JAVA_HOME and the version used in pom.xml should match. When JAVA_HOME is not set, Maven uses the java command from the PATH.

echo %JAVA_HOME%      # Windows cmd: C:\devsetup\JDKs\jdk17
echo $JAVA_HOME       # Linux and macOS: /usr/lib/jvm/java-21-openjdk-amd64

The Java version configured in the compiler plugin can be less than the JAVA_HOME version, but it must not be greater than it.

JAVA_HOME	pom.xml	Works?
17	17	Yes
21	17	Yes
25	21	Yes
17	21	No
21	25	No

3. Fixing the Error

We have two directions. If the project should move to the new Java version, we give Maven a newer JDK, either through JAVA_HOME or through a toolchain. If the project must stay on the old version, for example because the production servers still run Java 21, we lower the release value in pom.xml.

3.1. Pointing JAVA_HOME to the Newer JDK

We install the new JDK and set JAVA_HOME to its folder. The commands differ by operating system.

• On Windows, we set the variable in System Properties > Environment Variables, or with setx JAVA_HOME “C:\devsetup\JDKs\jdk25” in a command window. Without admin rights, we can set a user variable instead.
• On macOS, we add export JAVA_HOME=$(/usr/libexec/java_home -v 25) to ~/.zshrc.
• On Linux, we add export JAVA_HOME=/usr/lib/jvm/jdk-25 (the folder of our JDK) to ~/.bashrc.

Do not forget to open a new terminal window after updating the JAVA_HOME variable. Environment variables take effect only in newly launched windows and terminals. Similarly, if you are compiling the application in IntelliJ or any other IDE, close the IDE and open it again for the changes to take effect.

After that, mvn -v shows the new version, and the build passes.

Java version: 25.0.4.1, vendor: Eclipse Adoptium, runtime: /opt/jdk-25

3.2. Setting the Java Version in pom.xml

The maven.compiler.release property sets the release option for the compiler plugin. When the team decides to stay on Java 21 for another release, we set the property to 21, and the build works on JDK 21 and JDK 25.

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

A Spring Boot project sets the version with the java.version property instead, and spring-boot-starter-parent passes the value to maven.compiler.release. We change only java.version.

<properties>
  <java.version>21</java.version>
</properties>

We prefer release over source and target, because release also checks that the code uses only the API of that Java version. For example, with JDK 25 and release 21, the compiled classes have class file version 65 (Java 21) and run on a Java 21 server. More options are in setting the Java version in Maven.

3.3. Compiling With a Maven Toolchain

A toolchain lets Maven run on one JDK and compile with another one. It helps when several projects on one machine need different JDKs, so we do not switch JAVA_HOME for each build.

We list the installed JDKs once in ~/.m2/toolchains.xml.

<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>25</version>
    </provides>
    <configuration>
      <jdkHome>/opt/jdk-25</jdkHome>
    </configuration>
  </toolchain>
</toolchains>

In pom.xml, the jdkToolchain parameter of the compiler plugin picks the JDK by version.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.16.0</version>
  <configuration>
    <release>25</release>
    <jdkToolchain>
      <version>25</version>
    </jdkToolchain>
  </configuration>
</plugin>

With Maven running on JDK 21, the compiler plugin forks javac from JDK 25, and the build passes.

[INFO] Toolchain in maven-compiler-plugin: JDK[/opt/jdk-25]
[INFO] Compiling 1 source file with javac [forked debug release 25] to target/classes
[INFO] BUILD SUCCESS

The toolchain applies only to the plugins that we configure, so the tests still run on JDK 21. The maven-surefire-plugin has the same jdkToolchain parameter for the test run. The toolchains guide shows the maven-toolchains-plugin, which selects one JDK for all plugins.

3.4. Fixing the Error in IntelliJ IDEA

In IntelliJ IDEA, the same problem shows up as java: error: release version 25 not supported. IntelliJ IDEA has its own JDK settings, so a correct JAVA_HOME alone does not fix the IDE build.

• File > Project Structure > Project > SDK sets the JDK that builds the project. We select JDK 25 or newer.
• Settings > Build, Execution, Deployment > Build Tools > Maven > Runner > JRE sets the JDK for Maven goals started from the IDE. We select the same JDK.
• Settings > Build, Execution, Deployment > Compiler > Java Compiler has a Target bytecode version per module. We leave it empty, so IntelliJ IDEA takes the value from pom.xml.

After the change, we reload the Maven project, so IntelliJ IDEA reads pom.xml again.

4. Fixing the Error on a CI Server or in Docker

A build that passes on our laptop can still fail on the build server, because the server has its own JDK. For example, a Docker build that starts from a maven image with JDK 21 fails as soon as pom.xml asks for release 25. The image tag names the JDK, so we pick a tag with JDK 25.

FROM maven:3.9-eclipse-temurin-25 AS build
WORKDIR /app
COPY . .
RUN mvn -B clean package

In GitHub Actions, the java-version input of actions/setup-java sets the JDK for the job.

- uses: actions/setup-java@v6
  with:
    distribution: temurin
    java-version: '25'
- run: mvn -B clean package

To get a clear message instead of a compiler error, the Maven Enforcer Plugin can check the JDK version at the start of the build and stop with a readable rule message.

5. Release Version Not Supported FAQs

5.1. Can JDK 25 Compile a Project for Java 21?

Yes. A JDK compiles for its own version and every older supported version. With JDK 25 and maven.compiler.release 21, javac writes class files with version 65, so the jar runs on Java 21.

5.2. Why Do We Get “release version 5 not supported”?

The release value is too old for the JDK. New JDKs drop the oldest Java versions, and JDK 25 accepts release 8 or later. Old projects without any Java version in pom.xml get the default of the compiler plugin, which was 1.5 in versions before 3.8.0. IntelliJ IDEA imports that default as language level 5 and reports java: error: release version 5 not supported, whereas Maven reports “Source option 5 is no longer supported. Use 8 or later.”

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

We fix it by setting maven.compiler.release to a current version, as in section 3.2. Release 8 still compiles on JDK 25, but javac warns that “source value 8 is obsolete and will be removed in a future release”.

5.3. Why Does the Build Work in the Terminal but Fail in IntelliJ IDEA?

The terminal and IntelliJ IDEA use different JDK settings. The terminal uses JAVA_HOME, whereas IntelliJ IDEA uses the Project SDK and the Maven Runner JRE from section 3.4. We set all of them to the same JDK.

6. Conclusion

The error “release version X not supported” means that Maven compiles with a JDK older than the Java version in pom.xml. The command mvn -v shows the JDK that Maven uses, and the version in pom.xml must not be greater than it.

We fix the error by pointing JAVA_HOME to the newer JDK and opening a new terminal, by using a Maven toolchain, or by lowering maven.compiler.release when the project must stay on the old version. In IntelliJ IDEA and on CI servers, the JDK is set separately, so we update the Project SDK, the Maven Runner JRE, the Docker image or the setup-java version too.

7. References

• Maven Compiler Plugin: Setting the –release option
• Guide to Using Toolchains
• JEP 247: Compile for Older Platform Versions
• javac command (Java 25)
• IntelliJ IDEA: Maven Runner settings

Happy Learning !!