apache/maven · error · PluginDescriptorParsingException

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

Error message

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

What it means

A wrapper around IOExceptions raised while locating and reading the plugin descriptor: it covers both real I/O failures while opening the jar entry or plugin.xml stream and the 'No plugin descriptor found' sentinel from the same try block. The PluginDescriptorParsingException names the plugin, the absolute artifact path and the cause message.

Source

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

                                () -> pluginJar.getInputStream(pluginDescriptorEntry),
                                plugin,
                                pluginFile.getAbsolutePath());
                    }
                }
            } else {
                File pluginXml = new File(pluginFile, getPluginDescriptorLocation());

                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";
    }

View on GitHub (pinned to e4093d4e12)

Solutions

Read the cause message first: 'No plugin descriptor found' means the artifact is not a plugin; an I/O message means the jar may be corrupt.
Verify the artifact: unzip -t on the jar in the local repository to test archive integrity.
Delete the artifact folder under ~/.m2/repository and rebuild with -U to re-download.
Confirm the coordinates are a Maven plugin (packaging maven-plugin) before retrying.

Example fix

rm -rf ~/.m2/repository/<group-path>/<artifactId>/<version>
mvn -U groupId:artifactId:version:help

Defensive patterns

Strategy: validation

Validate before calling

unzip -t "$ART" > /dev/null || { echo 'corrupt plugin artifact: ' "$ART"; exit 1; }

Try / catch

try {
    descriptor = pluginManager.getPluginDescriptor(plugin, repos, session.getRepositorySession());
} catch (PluginDescriptorParsingException e) {
    String cause = String.valueOf(e.getCause() == null ? "" : e.getCause().getMessage());
    if (cause.contains("No plugin descriptor found")) {
        // wrong artifact, do not retry; otherwise purge and refetch
    }
    throw e;
}

Prevention

Verify jar integrity after flaky downloads before running builds
Configure checksum enforcement on repositories to reject corrupt artifacts
Prefer stable mirrors and purge suspect artifacts with mvn -U

When it happens

Trigger: The plugin.xml entry is unreadable from a truncated jar; a filesystem error while reading the local artifact; the missing-descriptor condition (no META-INF/maven/plugin.xml) surfaces through this wrapper with that text as the cause message.

Common situations: Corrupted downloads from flaky mirrors; disks or antivirus locking jar files mid-read; artifacts replaced by HTML error pages saved as jars.

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/58caefee4b748d00. Report an issue: GitHub.