[Solved] Maven-compiler-plugin: release version 21 not supported

When upgrading the Java/JDK version in a Maven project, we may encounter the error that a specific release version X is not supported. In this article, we will learn to fix this error and understand the root cause behind this exception.

1. The Problem

I encountered this error when upgrading an application from Java 17 to Java 21. I was using the IntelliJ idea IDE, although it does not matter much. You can encounter this issue in other IDEs as well as in the terminal/command line as well.

The error looks like this:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.11.0:compile (default-compile) 
on project My-Project: Fatal error compiling: invalid target release: 21 -> [Help 1]
...
...

2. The Root Cause

This error typically occurs when there is a mismatch between the Java version used for compiling your Maven project and the target Java version specified in the project’s configuration.

The Java version used for compiling the project can be checked by running the ‘mvn -v‘ command on the terminal. Currently, it is pointing at Java 17.

$ mvn -v

# Output

Apache Maven 3.8.1 (05c21c65bdfed0f71a2f2ada8b84da59348c4c5d)
Maven home: C:\devsetup\maven\bin\..
Java version: 17, vendor: Oracle Corporation, runtime: C:\devsetup\JDKs\jdk17
Default locale: en_IN, platform encoding: UTF-8
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

Internally it uses the JAVA_HOME environment variable, so ultimately your JAVA_HOME located Java version and the version used in pom.xml should match.

echo %JAVA_HOME%

# Output

C:\devsetup\JDKs\jdk17

The JDK version configured in the Maven compiler plugin is as follows. It is trying to use Java 21.

<build>
	<plugins>
		<plugin>
			<artifactId>maven-compiler-plugin</artifactId>
			<version>3.8.1</version>
			<configuration>
				<source>21</source>
				<target>21</target>
			</configuration>
		</plugin>
		...
		...
	<plugins>
<build>

3. The Solution

To solve the “release version not supported” issue, we must make sure that the JAVA_HOME pointed version and the compiler plugin configured versions are the same. The Compiler configured Java version can be less than the JAVA_HOME pointed version, but it MUST NOT be greater than it.

JAVA_HOME	Pom.xml	Works?
17	17	YES
21	17	YES
17	21	NO

After pointing the JAVA_HOME to Java 21 distribution and opening a new terminal window, we can compile the project successfully.

Do not forget to open a new ternimal window/command line after updating the JAVA_HOME variable. Environment variables take effect only in newly launched windows/ternimals.

Similarily, if you are compiling the application in IntelliJ or any IDE, the close the IDE and open again for changes to take effect.

4. Conclusion

This short Java tutorial discussed the root cause and the solution behind the error “Maven-compiler-plugin: release version not supported“. This can happen for any release of Java version when we upgrade the project dependencies.

The most important thing to remember is to relaunch the IDE or terminal window after updating the JAVA_HOME environment variable.

Happy Learning !!