apache/maven · error · IllegalStateException

Required Maven version {} is not met by current version {}

Error message

Required Maven version {} is not met by current version {}

What it means

When a plugin declares <prerequisites><maven>X</maven></prerequisites>, MavenPluginMavenPrerequisiteChecker compares it against the running Maven using runtimeInformation.isMavenVersion(X) (a version-range containment check). If the check returns false, Maven aborts plugin use with IllegalStateException naming both the required and current Maven versions. An invalid/unparseable prerequisite string only logs a warning and returns; only a well-formed but unmet requirement throws.

Source

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

    public void accept(PluginDescriptor pluginDescriptor) {
        String requiredMavenVersion = pluginDescriptor.getRequiredMavenVersion();

        boolean isBlankVersion =
                requiredMavenVersion == null || requiredMavenVersion.trim().isEmpty();

        if (!isBlankVersion) {
            boolean isRequirementMet = false;
            try {
                isRequirementMet = runtimeInformation.isMavenVersion(requiredMavenVersion);
            } catch (IllegalArgumentException e) {
                logger.warn(
                        "Could not verify plugin's Maven prerequisite as an invalid version is given in "
                                + requiredMavenVersion,
                        e);
                return;
            }
            if (!isRequirementMet) {
                throw new IllegalStateException("Required Maven version " + requiredMavenVersion
                        + " is not met by current version " + runtimeInformation.getMavenVersion());
            }
        }
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

1. Upgrade Maven to at least the required version (prefer the Maven Wrapper: .mvn/wrapper/maven-wrapper.properties distributionUrl).
2. Pin a version of the plugin that is compatible with the Maven you must keep running.
3. If you own the plugin, relax or widen the <prerequisites><maven> range so it contains the Maven versions you support.

Example fix

# before: CI Maven too old for the plugin
mvn org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile  # fails: requires Maven 3.6.3

# after: pin wrapper distribution
# .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip
./mvnw org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile

org.apache.maven.artifact.versioning.DefaultArtifactVersion running =
        new org.apache.maven.artifact.versioning.DefaultArtifactVersion(runtimeInformation.getMavenVersion());
org.apache.maven.artifact.versioning.DefaultArtifactVersion required =
        new org.apache.maven.artifact.versioning.DefaultArtifactVersion("3.6.3");
if (running.compareTo(required) < 0) {
    // select an older plugin version or fail with an actionable message before the build starts
}

try {
    return pluginManager.getPluginDescriptor(plugin, repos, session);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Required Maven version")) {
        // downgrade the pinned plugin version and retry once
    }
    throw e;
}

When it happens

Trigger: Loading/executing a plugin whose POM has a maven prerequisite (version or range) that does not contain the running Maven version: e.g. plugin requires 3.6.3 while running 3.5.0, or requires [3.0,3.8) while running Maven 3.8.x/4.x which falls outside the range.

Common situations: CI images or developer machines pinned to an old Maven while build plugins move forward (e.g. maven-compiler-plugin 3.13+ requires Maven 3.6.3); prerequisite ranges with an upper bound that excludes the Maven actually in use; switching a project to Maven 4 while a plugin caps the range below it.

Related errors

• Could not parse current Java version
• Unable to read Maven version from maven-core
• The consumer POM for %s cannot be downgraded to model versio
• Cannot inline property {}
• A required class was missing while executing {}: {}

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