apache/maven · error · IllegalArgumentException

Invalid 'requiredJavaVersion' given in plugin descriptor

Error message

Invalid 'requiredJavaVersion' given in plugin descriptor

What it means

MavenPluginJavaPrerequisiteChecker tried to parse the plugin descriptor's requiredJavaVersion as a Maven version constraint and versionScheme.parseVersionConstraint threw InvalidVersionSpecificationException, so it rethrows IllegalArgumentException naming the culprit field. The plugin itself ships malformed metadata — the string is not valid version or range syntax (e.g. '17+', '>=1.8', unbalanced brackets).

Source

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

    @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);
        }
        if (constraint.getRange() == null) {
            return constraint.getVersion().compareTo(current) <= 0;
        }
        return constraint.containsVersion(current);
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

If you own the plugin, fix the descriptor to valid syntax: plain version ('17') or Maven range ('[17,)').
Regenerate the descriptor rather than hand-editing, so the value round-trips through the plugin plugin's validation.
If third-party, report the malformed requiredJavaVersion to the plugin project and use a fixed release.
As a temporary workaround, build an older plugin version without the metadata or remove the prerequisite locally and reinstall.
Add a unit test that parses requiredJavaVersion with GenericVersionScheme so CI catches it.

Example fix

<!-- before: not valid Maven constraint syntax -->
<requiredJavaVersion>17+</requiredJavaVersion>

<!-- after: valid plain version or open-ended range -->
<requiredJavaVersion>[17,)</requiredJavaVersion>

Defensive patterns

Strategy: validation

Validate before calling

// plugin authors: validate the descriptor value in a unit test, exactly as Maven will parse it
import org.apache.maven.artifact.versioning.GenericVersionScheme;

@Test
void requiredJavaVersionIsParsable() throws Exception {
    String v = new MojoDescriptorBuilder() /* your descriptor source */ .getRequiredJavaVersion();
    if (v != null && !v.isEmpty()) {
        new GenericVersionScheme().parseVersionConstraint(v); // throws InvalidVersionSpecificationException
    }
}

Try / catch

// embedder: detect the malformed-metadata case and name the plugin at fault
try {
    prerequisiteChecker.accept(pluginDescriptor);
} catch (IllegalArgumentException e) {
    if (e.getCause() instanceof InvalidVersionSpecificationException) {
        log.error("plugin {} ships invalid requiredJavaVersion '{}'; use a version or range like [17,)"
                .formatted(pluginDescriptor.getId(), pluginDescriptor.getRequiredJavaVersion()));
    }
    throw e;
}

Prevention

Never hand-edit plugin.xml metadata; regenerate the descriptor from the build.
Use Maven range syntax for prerequisites ([17,), [1.8,11)) — not >=, ^, or + operators.
Add a descriptor-validation unit test to every plugin build so CI rejects bad metadata.
For consumers: pin plugin versions you have already validated in a scratch build.

When it happens

Trigger: Hand-edited plugin.xml or a descriptor generator writing non-Maven syntax; typo in the requiredJavaVersion property used to produce the descriptor; plugin built with a custom packaging that never validated the value.

Common situations: Developers assuming semver/npm-style operators ('>=17', '^17'); missing closing bracket in ranges ('[1.8'); copy-paste from README examples of other ecosystems.

Related errors

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