apache/maven · error · PluginResolutionException

Plugin ${plugin.getId()} or one of its dependencies could no

Error message

Plugin ${plugin.getId()} or one of its dependencies could not be resolved:
	${exceptionMessages}

What it means

DefaultPluginDependenciesResolver.readArtifactDescriptor failed: Maven could not read the plugin's artifact descriptor — its POM — because the resolver threw ArtifactDescriptorException (POM missing, malformed XML, unresolvable parent, or a transfer error). The resulting PluginResolutionException carries every underlying exception, so the message lists what the repository system actually returned.

Source

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

            if (logger.isWarnEnabled() && !result.getRelocations().isEmpty()) {
                String message =
                        pluginArtifact instanceof RelocatedArtifact relocated ? ": " + relocated.getMessage() : "";
                logger.warn(
                        "The artifact {} has been relocated to {}{}",
                        result.getRelocations().get(0),
                        pluginArtifact,
                        message);
            }

            String requiredMavenVersion = (String) result.getProperties().get("prerequisites.maven");
            if (requiredMavenVersion != null) {
                Map<String, String> props = new LinkedHashMap<>(pluginArtifact.getProperties());
                props.put("requiredMavenVersion", requiredMavenVersion);
                pluginArtifact = pluginArtifact.setProperties(props);
            }
        } catch (ArtifactDescriptorException e) {
            throw new PluginResolutionException(plugin, e.getResult().getExceptions(), e);
        }

        try {
            ArtifactRequest request = new ArtifactRequest(pluginArtifact, repositories, REPOSITORY_CONTEXT);
            request.setTrace(trace);
            pluginArtifact = repoSystem.resolveArtifact(session, request).getArtifact();
        } catch (ArtifactResolutionException e) {
            throw new PluginResolutionException(plugin, e.getResult().getExceptions(), e);
        }

        return pluginArtifact;
    }

    /**
     * @since 3.3.0
     * @deprecated Is unused since 3.10+
     */
    @Deprecated

View on GitHub (pinned to e4093d4e12)

Solutions

Open/curl the plugin POM URL (from the exception or repo manager) and check what is actually served.
If the POM is genuinely missing, use another existing version or ask the publisher to fix the deployment.
Delete the cached directory under ~/.m2/repository for that plugin and re-run with mvn -U.
Fix <parent> reachability if you publish the plugin yourself; validate the POM with a local mvn -f plugin.pom verify.
Check mirrors/proxies when the server answers with non-XML content (often visible in the exception text).

Example fix

# before: stale/broken plugin POM cached locally, descriptor read fails
# after: verify the POM is served, purge the local copy, force refresh
curl -fsSI https://repo.example.com/org/example/example-maven-plugin/1.0.0/example-maven-plugin-1.0.0.pom
rm -rf ~/.m2/repository/org/example/example-maven-plugin/1.0.0
mvn -U verify

Defensive patterns

Strategy: validation

Validate before calling

# before the build, confirm every plugin POM you depend on is served correctly
for gav in org.example:example-maven-plugin:1.0.0 org.example:other-plugin:2.0.5; do
  g=${gav%%:*}; rest=${gav#*:}; a=${rest%%:*}; v=${rest##*:}
  path=$(echo $g | tr '.' '/')/$a/$v/$a-$v.pom
  curl -fsSI https://repo.example.com/$path > /dev/null || echo "MISSING POM: $gav"
done

Try / catch

// embedder: expose the underlying descriptor-read failure
try {
    pluginDependenciesResolver.resolvePlugin(plugin, repositories, session);
} catch (PluginResolutionException e) {
    Throwable c = e.getCause();
    if (c instanceof ArtifactDescriptorException ade) {
        // ade.getResult().getExceptions() lists each POM-level problem (missing, invalid, transfer)
        reportDescriptorFailure(plugin, ade.getResult().getExceptions());
    }
    throw e;
}

Prevention

After mvn deploy, verify both POM and JAR exist in the repo manager for the released version.
Publish plugins with a resolvable parent (or flatten the POM) so descriptor reads cannot fail downstream.
Purge local copies of a plugin before re-testing against a fixed repository.
Monitor repository proxies: HTML error pages instead of XML surface as this exact error.

When it happens

Trigger: Plugin POM 404 (version exists in metadata but POM was never deployed or was removed); POM present but invalid; POM's own <parent> unresolvable from the configured repos; repository returning an HTML error page instead of XML; cached corrupt POM in the local repository.

Common situations: Broken releases in repo managers (metadata updated, artifacts missing); interrupted deploys; proxy servers injecting error pages; local repository corruption after failed downloads.

Related errors

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