apache/maven · error · PluginConfigurationException

Cannot setup plugin realm [mojoDescriptor=${mojoDescriptor.g

Error message

Cannot setup plugin realm [mojoDescriptor=${mojoDescriptor.getId()}, pluginDescriptor=${pluginDescriptor.getId()}]

What it means

When a mojo is configured, Maven lazily builds the plugin realm if it does not exist yet; if resolving the plugin's own dependencies fails (PluginResolutionException - artifact missing, unreachable, or version unresolvable), it is rethrown as PluginConfigurationException 'Cannot setup plugin realm [mojoDescriptor=..., pluginDescriptor=...]' and the build fails.

Source

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

        return foreignImports;
    }

    @Override
    public <T> T getConfiguredMojo(Class<T> mojoInterface, MavenSession session, MojoExecution mojoExecution)
            throws PluginConfigurationException, PluginContainerException {
        MojoDescriptor mojoDescriptor = mojoExecution.getMojoDescriptor();

        PluginDescriptor pluginDescriptor = mojoDescriptor.getPluginDescriptor();

        ClassRealm pluginRealm = pluginDescriptor.getClassRealm();

        if (pluginRealm == null) {
            try {
                setupPluginRealm(pluginDescriptor, session, null, null, null);
            } catch (PluginResolutionException e) {
                String msg = "Cannot setup plugin realm [mojoDescriptor=" + mojoDescriptor.getId()
                        + ", pluginDescriptor=" + pluginDescriptor.getId() + "]";
                throw new PluginConfigurationException(pluginDescriptor, msg, e);
            }
            pluginRealm = pluginDescriptor.getClassRealm();
        }

        if (logger.isDebugEnabled()) {
            logger.debug("Loading mojo " + mojoDescriptor.getId() + " from plugin realm " + pluginRealm);
        }

        // We are forcing the use of the plugin realm for all lookups that might occur during
        // the lifecycle that is part of the lookup. Here we are specifically trying to keep
        // lookups that occur in contextualize calls in line with the right realm.
        ClassRealm oldLookupRealm = container.setLookupRealm(pluginRealm);

        ClassLoader oldClassLoader = Thread.currentThread().getContextClassLoader();
        Thread.currentThread().setContextClassLoader(pluginRealm);

        try {
            if (mojoDescriptor.isV4Api()) {

View on GitHub (pinned to e4093d4e12)

Solutions

1. Inspect the cause (PluginResolutionException) - it names exactly which artifact failed and why.
2. Add or fix the <pluginRepository> entry hosting the plugin's dependencies; plugin artifacts resolve only from plugin repositories.
3. If offline, first run an offline-preparation build (go-offline-maven-plugin) or drop -o for one full pass.
4. Delete the failing artifact's folder in the local repository and rebuild with -U.

Example fix

<!-- before: dependency available only in <repositories> -->
<!-- after: also declare it where plugins can resolve it -->
<pluginRepositories>
  <pluginRepository>
    <id>corp-plugins</id>
    <url>https://nexus.corp/repo/plugins</url>
  </pluginRepository>
</pluginRepositories>

mvn -q de.qaware.maven:go-offline-maven-plugin:2.10.0:resolve-dependencies \
  || { echo 'plugin classpath not fully resolvable - fix before offline build'; exit 1; }

try {
    mojo = pluginManager.getConfiguredMojo(mojoInterface, session, mojoExecution);
} catch (PluginConfigurationException e) {
    if (e.getCause() instanceof PluginResolutionException) {
        // name the unresolvable artifact and repo so users know it is a fetch problem, not code
        log.error("unresolved plugin dependency: {}", e.getCause().getMessage());
    }
    throw e;
}

When it happens

Trigger: Plugin dependencies cannot be downloaded: the hosting repository is not configured as a <pluginRepository>, offline mode (-o) runs against a cold local repository, a version range resolves to nothing, or the artifact was removed from the remote.

Common situations: Air-gapped/offline builds; corporate mirrors lagging new plugin releases; snapshots not resolved because repository policies disable snapshot updates; version numbers typed by hand.

Related errors

• Unable to download the artifact from any repository
• {} could not be retrieved from repository: {} due to an erro
• A dependency has introduced a cycle
• Unable to get a selected Version for {}
• Invalid remote repository {}

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