apache/maven · error · IllegalStateException

Required Java version {} is not met by current version: {}

Error message

Required Java version {} is not met by current version: {}

What it means

The plugin descriptor carries a non-empty requiredJavaVersion, and MavenPluginJavaPrerequisiteChecker compared it against the running JVM's java.version with a Maven VersionConstraint; the constraint does not match, so it throws IllegalStateException and plugin setup aborts before any mojo runs. Note the check applies to the JVM running Maven itself, not to toolchain-selected compilers.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/plugin/internal/MavenPluginJavaPrerequisiteChecker.java:48

import org.eclipse.aether.version.VersionScheme;

@Named
@Singleton
public class MavenPluginJavaPrerequisiteChecker implements MavenPluginPrerequisitesChecker {
    private final VersionScheme versionScheme;

    @Inject
    public MavenPluginJavaPrerequisiteChecker(VersionScheme versionScheme) {
        this.versionScheme = versionScheme;
    }

    @Override
    public void accept(PluginDescriptor pluginDescriptor) {
        String requiredJavaVersion = pluginDescriptor.getRequiredJavaVersion();
        if (requiredJavaVersion != null && !requiredJavaVersion.isEmpty()) {
            String currentJavaVersion = System.getProperty("java.version");
            if (!matchesVersion(requiredJavaVersion, currentJavaVersion)) {
                throw new IllegalStateException("Required Java version " + requiredJavaVersion
                        + " is not met by current version: " + currentJavaVersion);
            }
        }
    }

    boolean matchesVersion(String requiredVersion, String currentVersion) {
        VersionConstraint constraint;
        try {
            constraint = versionScheme.parseVersionConstraint(requiredVersion);
        } catch (InvalidVersionSpecificationException e) {
            throw new IllegalArgumentException("Invalid 'requiredJavaVersion' given in plugin descriptor", e);
        }
        Version current;
        try {
            current = versionScheme.parseVersion(currentVersion);
        } catch (InvalidVersionSpecificationException e) {
            throw new IllegalStateException("Could not parse current Java version", e);
        }

View on GitHub (pinned to e4093d4e12)

Solutions

Run Maven itself with a JDK satisfying the constraint (set JAVA_HOME / update the CI image).
Pin an older plugin version whose requiredJavaVersion matches your JDK.
If the range excludes your newer JDK (upper-bound style), upgrade the plugin or choose a version with an open-ended range.
If you own the plugin, relax/correct requiredJavaVersion (prefer open-ended lower bounds like [17,)).
Remember toolchains do not help: the prerequisite is checked against the JVM Maven runs on.

Example fix

# before: Maven runs on a JDK older than the plugin requires
JAVA_HOME=/usr/lib/jvm/java-8-openjdk mvn verify
# -> IllegalStateException: Required Java version 17 is not met by current version: 1.8.0_392

# after: run Maven on a compliant JDK (or pin an older plugin version)
JAVA_HOME=/usr/lib/jvm/java-17-openjdk mvn verify

Defensive patterns

Strategy: validation

Validate before calling

# gate the build on the JDK requirement before Maven loads any plugin
required=17
current=$(mvn -v | awk '/Java version/ {gsub(/,/, "", $3); print $3}')
lowest=$(printf '%s\n%s' "$required" "$current" | sort -V | head -1)
[ "$lowest" = "$required" ] || { echo "Maven needs JDK >= $required, running $current"; exit 1; }
mvn verify

Try / catch

// embedder: check the prerequisite before the plugin manager does
String required = pluginDescriptor.getRequiredJavaVersion();
if (required != null && !required.isEmpty()
        && !versionScheme.parseVersionConstraint(required)
            .containsVersion(versionScheme.parseVersion(System.getProperty("java.version")))) {
    throw new IllegalStateException("select a JDK matching " + required + " before loading "
            + pluginDescriptor.getId());
}

Prevention

Enforce the fleet's minimum JDK with maven-enforcer-plugin requireJavaVersion in the root POM.
Pin container/CI images to JDK versions that satisfy every plugin you use.
Note toolchains do not exempt you: the check runs against the JVM that runs Maven.
Track requiredJavaVersion bumps in plugin release notes before upgrading.

When it happens

Trigger: Plugin requires e.g. [17,) while Maven runs on JDK 8/11; range with an exclusive upper bound (e.g. [1.8,1.9) or (,17)) excluding the current newer JDK; CI matrices where one job still uses an older image; CI using a newer JDK than the range allows.

Common situations: Upgrading a plugin whose new major bumped the required JDK; legacy ranges written when Java 8/9 were current but now exclude modern JVMs; developers with mismatched JAVA_HOME; container images pinned to old JDKs.

Related errors

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/ccdd1726be32650d. Report an issue: GitHub.