Introduction

The error invalid flag: --release usually means Maven is invoking a Java compiler that is too old to understand the --release option. The confusing part is that IntelliJ may show one JDK in the project settings while Maven actually runs with another.

What the --release flag means

--release is a javac option introduced in newer Java toolchains to compile against a specific Java platform level cleanly. For example:

javac --release 17 Hello.java

If the compiler process is really using JDK 8, that flag is invalid, so Maven fails before compilation even starts.

This is why the error is usually a toolchain mismatch, not a code problem.

Where the mismatch usually happens

There are three places to check:

• the JDK configured for the IntelliJ project
• the JDK used by Maven inside IntelliJ
• the compiler settings in pom.xml

A project may target Java 17 in pom.xml, while IntelliJ runs Maven with Java 8 from JAVA_HOME or its internal Maven runner settings.

Check the Maven compiler configuration

A typical Maven setup using release looks like this:

1<properties>
2    <maven.compiler.release>17</maven.compiler.release>
3</properties>
4
5<build>
6    <plugins>
7        <plugin>
8            <groupId>org.apache.maven.plugins</groupId>
9            <artifactId>maven-compiler-plugin</artifactId>
10            <version>3.11.0</version>
11        </plugin>
12    </plugins>
13</build>

This is fine only if Maven is run by a compatible JDK. If the build still uses an old compiler, --release becomes the problem indicator.

Verify what Java Maven is actually using

Run this from the terminal:

mvn -version

The output tells you which Java version Maven is using. If it reports Java 8 while your pom.xml uses maven.compiler.release, you have found the real issue.

Inside IntelliJ, also check the Maven runner JDK. The IDE project SDK and the Maven import or runner JDK are related settings, but they are not always the same setting.

Typical fixes

Fix 1: run Maven with a newer JDK

If your project is supposed to use Java 11, 17, or later, point IntelliJ and Maven to that JDK and keep maven.compiler.release.

Fix 2: remove release for old-JDK builds

If the project must really build with JDK 8, switch to source and target properties instead:

1<properties>
2    <maven.compiler.source>1.8</maven.compiler.source>
3    <maven.compiler.target>1.8</maven.compiler.target>
4</properties>

That avoids asking an old compiler to understand a flag it simply does not support.

Fix 3: align IntelliJ and environment settings

Make sure these all agree:

• 'JAVA_HOME'
• IntelliJ project SDK
• IntelliJ Maven runner JDK
• the Java version declared in pom.xml

Most --release errors disappear once the toolchain is aligned end to end.

Why the IDE makes this error feel stranger than it is

IntelliJ can compile code with its own configured SDK and still delegate Maven tasks to a different JDK. That split makes the problem feel random:

• code editor looks fine
• project SDK looks fine
• Maven build fails anyway

Once you realize Maven is a separate process with its own Java selection, the error becomes much easier to diagnose.

Common Pitfalls

The biggest pitfall is checking only the IntelliJ project SDK and assuming that is the same JDK Maven uses. It often is not.

Another issue is mixing maven.compiler.release with an old JAVA_HOME. The pom.xml can look perfectly modern while the actual compiler remains too old.

People also downgrade the compiler plugin version without solving the real mismatch. The plugin matters, but the JDK actually executing javac matters even more.

Finally, do not switch blindly between release, source, and target. Pick the configuration that matches the real toolchain you intend to support.

Summary

• 'invalid flag: --release usually means Maven is running with an older JDK than the build expects.'
• Check mvn -version first to see the actual Java version behind Maven.
• Align IntelliJ SDK settings, Maven runner settings, JAVA_HOME, and pom.xml.
• Use maven.compiler.release only with a compatible JDK.
• If the project truly targets JDK 8, use source and target instead of release.