apache/maven · error · IOException

No plugin descriptor found at ${pluginDescriptorLocation}

Error message

No plugin descriptor found at ${pluginDescriptorLocation}

What it means

Maven looked for the plugin descriptor at META-INF/maven/plugin.xml - as a jar entry of the plugin artifact and, for a directory-based plugin file, as a plain file - and found nothing. Without plugin.xml there are no mojos to execute, so the IOException is wrapped into PluginDescriptorParsingException and the build fails.

Source

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

                    if (pluginDescriptorEntry != null) {
                        pluginDescriptor = parsePluginDescriptor(
                                () -> 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;
    }

View on GitHub (pinned to e4093d4e12)

Solutions

  1. Confirm the coordinates refer to a real Maven plugin: check its documentation or metadata for packaging maven-plugin and a goal list.
  2. Invoke the goal in full groupId:artifactId:version:goal form to bypass prefix guessing.
  3. Delete the artifact's folder under ~/.m2/repository and rebuild with -U to force a clean re-download.
  4. For your own plugin, set <packaging>maven-plugin</packaging> so plugin.xml is generated into META-INF/maven.

Example fix

<!-- before -->
<packaging>jar</packaging>
<!-- after -->
<packaging>maven-plugin</packaging>
Defensive patterns

Strategy: validation

Validate before calling

ART="$HOME/.m2/repository/<group-path>/<artifactId>/<version>/<artifactId>-<version>.jar"
unzip -l "$ART" | grep -q 'META-INF/maven/plugin.xml' \
  || { echo "not a maven plugin (no descriptor): $ART"; exit 1; }

Try / catch

try {
    descriptor = pluginManager.getPluginDescriptor(plugin, repos, session.getRepositorySession());
} catch (PluginDescriptorParsingException e) {
    // check packaging of the coordinates before assuming a network problem
    throw new IllegalArgumentException(plugin.getId() + " is not resolvable as a plugin", e);
}

Prevention

When it happens

Trigger: The resolved coordinates are not a Maven plugin at all (a plain library jar invoked as groupId:artifactId:version:goal); the jar was built with packaging 'jar' instead of 'maven-plugin' so the descriptor was never generated; or the artifact in the local repository is corrupt/empty.

Common situations: Typo'd groupId/artifactId that still resolves to an existing library; plugin prefix resolution mapping to the wrong artifact; partial downloads after network failures; goals that moved to a different artifactId in newer releases.

Related errors

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