Maven "Fatal error compiling: invalid target release" - Fix JDK

Q: What causes Maven "Fatal error compiling: invalid target release"?

There are 2 common causes: java_home points at an older jdk and maven.compiler.release set higher than the toolchain. The runner’s JDK is older than the / in the compiler config.

By Daniel Zoghalchali·Latchkey

The maven-compiler-plugin was told to target a Java version newer than the JDK actually running the build. A JDK 17 cannot emit --release 21 bytecode - it does not know that version.

What this error means

Compilation aborts with Fatal error compiling: invalid target release: 21 (or similar). The number is the version your POM requests; the running JDK is older than it.

mvn output

[ERROR] Failed to execute goal
org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile)
on project app: Fatal error compiling: invalid target release: 21

Diagnose it: resolve the effective POM first

Maven merges parent POMs, profiles, and settings before it builds anything. The configuration causing your failure is frequently inherited or activated by a profile that is on locally and off in CI.

Terminal

# the fully resolved configuration Maven will actually use
mvn help:effective-pom | head -60

# which profiles are active here vs on your machine?
mvn help:active-profiles

# full error, offline-safe, no colour codes to confuse the log
mvn -B -e -X <goal> 2>&1 | tail -60

Common causes

JAVA_HOME points at an older JDK

The runner’s JDK is older than the <release>/<target> in the compiler config. CI defaulted to JDK 17 while the project targets 21.

maven.compiler.release set higher than the toolchain

A <maven.compiler.release>21</maven.compiler.release> (or --release 21) demands a JDK that understands version 21. An older JDK rejects it outright.

How to fix it

Set up the matching JDK in CI

Provision the JDK version your project targets so the compiler can emit that bytecode.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '21'
- run: mvn -B -version   # confirm Maven uses JDK 21

Align the release with the available JDK

If you cannot upgrade the JDK, lower the target. The release must be <= the running JDK.

pom.xml

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

How to prevent it

Pin the JDK version in CI with setup-java and assert it with mvn -version.
Keep maven.compiler.release and the provisioned JDK in lockstep.
Use Maven Toolchains to bind a specific JDK independent of JAVA_HOME.

Frequently asked questions

What causes Maven "Fatal error compiling: invalid target release"?

There are 2 common causes: java_home points at an older jdk and maven.compiler.release set higher than the toolchain. The runner’s JDK is older than the <release>/<target> in the compiler config.

How do I fix Maven "Fatal error compiling: invalid target release"?

There are 2 fixes depending on which cause you have: set up the matching jdk in ci and align the release with the available jdk. Work through them in order, since the first is the most common.

What does Maven "Fatal error compiling: invalid target release" actually mean?

Compilation aborts with Fatal error compiling: invalid target release: 21 (or similar).

How do I stop Maven "Fatal error compiling: invalid target release" happening again?

Pin the JDK version in CI with setup-java and assert it with mvn -version. The prevention section lists 3 changes that keep it from recurring.