apache/maven · error · PluginConfigurationException

An API incompatibility was encountered during configuration

Error message

An API incompatibility was encountered during configuration of mojo ${mojoDescriptor.getId()}: ${e.getClass().getName()}: ${e.getMessage()}

What it means

Mojo configuration failed with a LinkageError (NoSuchMethodError, IllegalAccessError, VerifyError, ...): the classes needed during configuration exist in the plugin realm but are binary-incompatible — typically the resolved version of a library differs from the one the plugin's converter or parameter types were compiled against. Maven reports the error class, message, and a realm dump via PluginConfigurationException.

Source

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

                    "Unable to retrieve component configurator " + configuratorId + " for configuration of mojo "
                            + mojoDescriptor.getId(),
                    e);
        } catch (NoClassDefFoundError e) {
            ByteArrayOutputStream os = new ByteArrayOutputStream(1024);
            PrintStream ps = new PrintStream(os);
            ps.println("A required class was missing during configuration of mojo " + mojoDescriptor.getId() + ": "
                    + e.getMessage());
            pluginRealm.display(ps);

            throw new PluginConfigurationException(mojoDescriptor.getPluginDescriptor(), os.toString(), e);
        } catch (LinkageError e) {
            ByteArrayOutputStream os = new ByteArrayOutputStream(1024);
            PrintStream ps = new PrintStream(os);
            ps.println("An API incompatibility was encountered during configuration of mojo " + mojoDescriptor.getId()
                    + ": " + e.getClass().getName() + ": " + e.getMessage());
            pluginRealm.display(ps);

            throw new PluginConfigurationException(mojoDescriptor.getPluginDescriptor(), os.toString(), e);
        } finally {
            if (configurator != null) {
                try {
                    container.release(configurator);
                } catch (ComponentLifecycleException e) {
                    logger.debug("Failed to release mojo configurator - ignoring.");
                }
            }
        }
    }

    private void validateParameters(
            MojoDescriptor mojoDescriptor, PlexusConfiguration configuration, ExpressionEvaluator expressionEvaluator)
            throws ComponentConfigurationException, PluginParameterException {
        if (mojoDescriptor.getParameters() == null) {
            return;
        }

View on GitHub (pinned to e4093d4e12)

Solutions

Read the LinkageError details: they name the class/member that mismatches; find that class in the realm dump to learn the offending artifact and version.
Pin the compatible version of that artifact under <plugin><dependencies>.
Upgrade the plugin (and siblings that share the dependency) to versions with a consistent dependency set.
Remove duplicate-class dependencies (shaded vs original) so only one variant remains in the realm.
If the mismatch is against JDK internals, run Maven on the JDK the plugin targets.

Example fix

// before: realm resolves asm 5.x but the plugin's converter needs asm 9 -> LinkageError during configuration
<plugin>
  <groupId>org.example</groupId>
  <artifactId>example-maven-plugin</artifactId>
  <version>1.0.0</version>
</plugin>

// after: pin the compatible library version inside the plugin
<plugin>
  <groupId>org.example</groupId>
  <artifactId>example-maven-plugin</artifactId>
  <version>1.0.0</version>
  <dependencies>
    <dependency>
      <groupId>org.ow2.asm</groupId>
      <artifactId>asm</artifactId>
      <version>9.6</version>
    </dependency>
  </dependencies>
</plugin>

Defensive patterns

Strategy: try-catch

Validate before calling

# pre-flight: inspect which versions of shared libraries the plugin realm actually resolves
mvn -X dependency:resolve-plugins 2>&1 | grep -E '(guava|commons-|asm|slf4j).*\.jar' | sort -u

Type guard

static boolean incompatibleDuringConfiguration(PluginConfigurationException e) {
    return e.getCause() instanceof LinkageError && !(e.getCause() instanceof NoClassDefFoundError);
}

Try / catch

try {
    executor.execute(session, mojoExecution);
} catch (PluginConfigurationException e) {
    if (e.getCause() instanceof LinkageError le && !(le instanceof NoClassDefFoundError)) {
        // pin the conflicting library under <plugin><dependencies>
        reportLinkageConflict(le);
    }
    throw e;
}

Prevention

Pin versions of libraries shared between plugins inside each <plugin><dependencies> block.
Avoid mixing shaded and original variants of the same library across plugin dependencies.
Re-test the full plugin set when changing the JDK that runs Maven.
Use -X output to review realm contents when introducing a new plugin.

When it happens

Trigger: Version mediation inside the plugin realm selects an incompatible build of a library used during configuration; duplicate classes from overlapping dependencies; parameter type compiled against a newer API than what the realm resolves.

Common situations: Shared libraries (ASM, Guava, commons-*) forced to old versions by other plugin dependencies; plugins mixing shaded and non-shaded variants of the same library; JDK differences exposing removed APIs.

Related errors

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