apache/maven · error · InvalidPluginDescriptorException

Invalid plugin descriptor for ${plugin.getId()} (${pluginFil

Error message

Invalid plugin descriptor for ${plugin.getId()} (${pluginFile})

What it means

The plugin descriptor was found and parsed, but semantic validation failed: the configured PluginValidators collected error strings (missing or invalid values in plugin.xml - plugin/mojo metadata, parameters, requirements) and Maven throws InvalidPluginDescriptorException listing every problem for the plugin id and artifact file.

Source

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

                if (pluginXml.isFile()) {
                    pluginDescriptor = parsePluginDescriptor(
                            () -> Files.newInputStream(pluginXml.toPath()), plugin, pluginXml.getAbsolutePath());
                }
            }

            if (pluginDescriptor == null) {
                throw new IOException("No plugin descriptor found at " + getPluginDescriptorLocation());
            }
        } catch (IOException e) {
            throw new PluginDescriptorParsingException(plugin, pluginFile.getAbsolutePath(), e);
        }

        List<String> errors = new ArrayList<>();
        pluginValidator.validate(pluginArtifact, pluginDescriptor, errors);

        if (!errors.isEmpty()) {
            throw new InvalidPluginDescriptorException(
                    "Invalid plugin descriptor for " + plugin.getId() + " (" + pluginFile + ")", errors);
        }

        pluginDescriptor.setPluginArtifact(pluginArtifact);

        return pluginDescriptor;
    }

    private String getPluginDescriptorLocation() {
        return "META-INF/maven/plugin.xml";
    }

    private PluginDescriptor parsePluginDescriptor(
            PluginDescriptorBuilder.StreamSupplier is, Plugin plugin, String descriptorLocation)
            throws PluginDescriptorParsingException {
        try {
            return builder.build(is, descriptorLocation);
        } catch (PlexusConfigurationException e) {

View on GitHub (pinned to e4093d4e12)

Solutions

Read every listed error line - the validators name the exact invalid entries in the descriptor.
Rebuild the plugin from source with a current, aligned maven-plugin-plugin so the descriptor is regenerated.
Never hand-edit plugin.xml inside a packaged jar.
If a validator extension is configured in the build, check its rules and relax or fix the descriptor accordingly.

Example fix

<!-- before: jar patched by overwriting plugin.xml -->
jar uf my-plugin.jar META-INF/maven/plugin.xml
<!-- after: rebuild properly so descriptor and code agree -->
mvn clean install -pl my-plugin

Defensive patterns

Strategy: validation

Validate before calling

xmllint --noout target/classes/META-INF/maven/plugin.xml \
  && echo 'descriptor xml well-formed' || echo 'descriptor broken'

Try / catch

try {
    descriptor = pluginManager.getPluginDescriptor(plugin, repos, session.getRepositorySession());
} catch (InvalidPluginDescriptorException e) {
    // e.getMessages() lists every invalid descriptor entry; surface them verbatim
    throw new IllegalStateException(String.join("; ", e.getMessages()), e);
}

Prevention

Never hand-edit plugin.xml inside packaged jars
Keep maven-plugin-plugin and maven-plugin-annotations versions aligned in plugin builds
Run descriptor validation as part of the plugin's own build

When it happens

Trigger: A hand-edited or code-generated plugin.xml with required elements missing; a descriptor produced by an incompatible maven-plugin-plugin version; shading or relocation mangling the packaged descriptor.

Common situations: Teams patching plugin jars instead of rebuilding; CI building plugins with mismatched maven-plugin-plugin/annotations versions; custom packaging mangling META-INF/maven/plugin.xml.

Related errors

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