What causes "Failed to retrieve plugin descriptor for {}: {}" in apache/maven?

Read the stack trace that follows in -X output - it names the real failure (NoSuchArtifact, invalid plugin.xml, prerequisite) and the plugin involved

apache/maven · warning

Failed to retrieve plugin descriptor for {}: {}

Error message

Failed to retrieve plugin descriptor for {}: {}

What it means

DefaultPluginPrefixResolver maps a goal prefix (the 'clean' in mvn clean, the 'help' in mvn help:effective-pom) to plugin coordinates. One strategy (doResolveFromProject) iterates plugins already declared in the project's POM(s) and loads each descriptor via pluginManager.loadPlugin; a candidate that fails to load (unresolvable artifact, broken plugin.xml, incompatible prerequisite) is logged with this warning and the loop continues. This variant is the debug-enabled form: it appends the full exception as the last argument so SLF4J prints the stack trace.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/plugin/prefix/internal/DefaultPluginPrefixResolver.java:178

            Set<Plugin> remainder = new LinkedHashSet<>(plugins);
            remainder.removeAll(candidates);
            result = doResolveFromProject(request, remainder);
        }
        return result;
    }

    private PluginPrefixResult doResolveFromProject(PluginPrefixRequest request, Collection<Plugin> plugins) {
        for (Plugin plugin : plugins) {
            try {
                PluginDescriptor pluginDescriptor =
                        pluginManager.loadPlugin(plugin, request.getRepositories(), request.getRepositorySession());

                if (request.getPrefix().equals(pluginDescriptor.getGoalPrefix())) {
                    return new DefaultPluginPrefixResult(plugin);
                }
            } catch (Exception e) {
                if (logger.isDebugEnabled()) {
                    logger.warn("Failed to retrieve plugin descriptor for {}: {}", plugin.getId(), e.getMessage(), e);
                } else {
                    logger.warn("Failed to retrieve plugin descriptor for {}: {}", plugin.getId(), e.getMessage());
                }
            }
        }

        return null;
    }

    private PluginPrefixResult resolveFromRepository(
            PluginPrefixRequest request, LinkedHashMap<String, Set<String>> candidates) {
        RequestTrace trace = RequestTrace.newChild(null, request);

        List<MetadataRequest> requests = new ArrayList<>();

        for (String pluginGroup : candidates.keySet()) {
            org.eclipse.aether.metadata.Metadata metadata =
                    new DefaultMetadata(pluginGroup, "maven-metadata.xml", DefaultMetadata.Nature.RELEASE_OR_SNAPSHOT);

View on GitHub (pinned to e4093d4e12)

Solutions

Read the stack trace that follows in -X output - it names the real failure (NoSuchArtifact, invalid plugin.xml, prerequisite) and the plugin involved
Fix or remove the broken plugin declaration in the POM/parent/profile it comes from (often a typo'd groupId or a version that no longer exists)
Delete the corrupted artifact directory under ~/.m2/repository/<group path>/<artifact> and retry with -U
Invoke with full coordinates (groupId:artifactId:version:goal) to bypass prefix search entirely

Example fix

<!-- before: typo makes the candidate unloadable during prefix search -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugn</artifactId>
  <version>3.13.0</version>
</plugin>
<!-- after -->
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.13.0</version>
</plugin>

Defensive patterns

Strategy: validation

Validate before calling

# preflight: force-load every declared plugin descriptor before the real build
mvn -q dependency:resolve-plugins

Prevention

Spell plugin coordinates exactly and pin versions so loadPlugin never probes missing artifacts
Invoke rarely-used goals with full coordinates groupId:artifactId:version:goal to skip prefix search over broken candidates
Run CI builds with -X when introducing new plugins so descriptor-load failures show their stack traces

When it happens

Trigger: Invoke a prefixed goal (mvn clean, mvn help:describe) with -X/debug logging while some plugin declared in the POM, a parent or an active profile cannot be loaded - e.g. typo'd coordinates, version not in any repository, corrupted local-repo artifact. Each broken candidate logs one such warning.

Common situations: Typos in groupId/artifactId in build or reporting sections; snapshot plugins removed from the remote repo; offline builds or proxies blocking artifact fetches; parent POMs referencing internal plugins unavailable outside the VPN.

Related errors

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