apache/maven · error · PluginDescriptorParsingException

Failed to parse plugin descriptor for ${plugin.getId()} (${d

Error message

Failed to parse plugin descriptor for ${plugin.getId()} (${descriptorLocation}): ${e.getMessage()}

What it means

PluginDescriptorBuilder.build() hit a PlexusConfigurationException while reading plugin.xml: the XML is malformed or structurally wrong (unparsable content, wrong root element, invalid nesting). It is wrapped as PluginDescriptorParsingException with the exact descriptor location so you know which entry is broken.

Source

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

                    "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) {
            throw new PluginDescriptorParsingException(plugin, descriptorLocation, e);
        }
    }

    @Override
    public MojoDescriptor getMojoDescriptor(
            Plugin plugin, String goal, List<RemoteRepository> repositories, RepositorySystemSession session)
            throws MojoNotFoundException, PluginResolutionException, PluginDescriptorParsingException,
                    InvalidPluginDescriptorException {
        PluginDescriptor pluginDescriptor = getPluginDescriptor(plugin, repositories, session);

        MojoDescriptor mojoDescriptor = pluginDescriptor.getMojo(goal);

        if (mojoDescriptor == null) {
            throw new MojoNotFoundException(goal, pluginDescriptor);
        }

        return mojoDescriptor;
    }

View on GitHub (pinned to e4093d4e12)

Solutions

Inspect the entry: unzip -p <jar> META-INF/maven/plugin.xml | head to see the actual content.
If it is garbage, delete the artifact folder under ~/.m2/repository and rebuild with -U (optionally switch mirrors).
If it is your own plugin, rebuild with mvn clean install so a fresh descriptor is packaged.
Run xmllint on the extracted file to pinpoint the XML error.

Example fix

unzip -p my-plugin.jar META-INF/maven/plugin.xml | xmllint -
# if it fails: purge and re-fetch
rm -rf ~/.m2/repository/<group-path>/my-plugin && mvn -U my-plugin:help

Defensive patterns

Strategy: validation

Validate before calling

unzip -p "$ART" META-INF/maven/plugin.xml | xmllint - \
  || echo 'plugin.xml is not valid XML: artifact corrupt, purge local copy'

Try / catch

try {
    descriptor = pluginManager.getPluginDescriptor(plugin, repos, session.getRepositorySession());
} catch (PluginDescriptorParsingException e) {
    if (e.getCause() instanceof PlexusConfigurationException) {
        // XML itself is broken: purge ~/.m2 path and refetch rather than debugging the POM
    }
    throw e;
}

Prevention

Enforce checksum verification for plugin repositories
Purge and re-download artifacts after mirror errors instead of retrying builds
Validate packaged plugin.xml with xmllint in the plugin's CI

When it happens

Trigger: A corrupted or truncated plugin.xml entry inside the jar, typically after a flaky download; a jar entry replaced with garbage by a broken mirror; a descriptor written by incompatible tooling.

Common situations: Partial downloads stored in the local repository; mirrors serving error pages; jars processed by zip tools that mangled entries.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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