{"record":{"id":"de7a30feb871ebd6","repo":"apache/maven","slug":"an-api-incompatibility-was-encountered-during-conf","errorCode":null,"errorMessage":"An API incompatibility was encountered during configuration of mojo ${mojoDescriptor.getId()}: ${e.getClass().getName()}: ${e.getMessage()}","messagePattern":"An API incompatibility was encountered during configuration of mojo (.+?): (.+?): (.+?)","errorType":"exception","errorClass":"PluginConfigurationException","httpStatus":null,"severity":"error","filePath":"impl/maven-core/src/main/java/org/apache/maven/plugin/internal/DefaultMavenPluginManager.java","lineNumber":863,"sourceCode":"                    \"Unable to retrieve component configurator \" + configuratorId + \" for configuration of mojo \"\n                            + mojoDescriptor.getId(),\n                    e);\n        } catch (NoClassDefFoundError e) {\n            ByteArrayOutputStream os = new ByteArrayOutputStream(1024);\n            PrintStream ps = new PrintStream(os);\n            ps.println(\"A required class was missing during configuration of mojo \" + mojoDescriptor.getId() + \": \"\n                    + e.getMessage());\n            pluginRealm.display(ps);\n\n            throw new PluginConfigurationException(mojoDescriptor.getPluginDescriptor(), os.toString(), e);\n        } catch (LinkageError e) {\n            ByteArrayOutputStream os = new ByteArrayOutputStream(1024);\n            PrintStream ps = new PrintStream(os);\n            ps.println(\"An API incompatibility was encountered during configuration of mojo \" + mojoDescriptor.getId()\n                    + \": \" + e.getClass().getName() + \": \" + e.getMessage());\n            pluginRealm.display(ps);\n\n            throw new PluginConfigurationException(mojoDescriptor.getPluginDescriptor(), os.toString(), e);\n        } finally {\n            if (configurator != null) {\n                try {\n                    container.release(configurator);\n                } catch (ComponentLifecycleException e) {\n                    logger.debug(\"Failed to release mojo configurator - ignoring.\");\n                }\n            }\n        }\n    }\n\n    private void validateParameters(\n            MojoDescriptor mojoDescriptor, PlexusConfiguration configuration, ExpressionEvaluator expressionEvaluator)\n            throws ComponentConfigurationException, PluginParameterException {\n        if (mojoDescriptor.getParameters() == null) {\n            return;\n        }\n","sourceCodeStart":845,"sourceCodeEnd":881,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/impl/maven-core/src/main/java/org/apache/maven/plugin/internal/DefaultMavenPluginManager.java#L845-L881","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: realm resolves asm 5.x but the plugin's converter needs asm 9 -> LinkageError during configuration\n<plugin>\n  <groupId>org.example</groupId>\n  <artifactId>example-maven-plugin</artifactId>\n  <version>1.0.0</version>\n</plugin>\n\n// after: pin the compatible library version inside the plugin\n<plugin>\n  <groupId>org.example</groupId>\n  <artifactId>example-maven-plugin</artifactId>\n  <version>1.0.0</version>\n  <dependencies>\n    <dependency>\n      <groupId>org.ow2.asm</groupId>\n      <artifactId>asm</artifactId>\n      <version>9.6</version>\n    </dependency>\n  </dependencies>\n</plugin>","handlingStrategy":"try-catch","validationCode":"# pre-flight: inspect which versions of shared libraries the plugin realm actually resolves\nmvn -X dependency:resolve-plugins 2>&1 | grep -E '(guava|commons-|asm|slf4j).*\\.jar' | sort -u","typeGuard":"static boolean incompatibleDuringConfiguration(PluginConfigurationException e) {\n    return e.getCause() instanceof LinkageError && !(e.getCause() instanceof NoClassDefFoundError);\n}","tryCatchPattern":"try {\n    executor.execute(session, mojoExecution);\n} catch (PluginConfigurationException e) {\n    if (e.getCause() instanceof LinkageError le && !(le instanceof NoClassDefFoundError)) {\n        // pin the conflicting library under <plugin><dependencies>\n        reportLinkageConflict(le);\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["maven","plugin","linkage-error","configuration","binary-incompatibility"],"backgroundTag":"class-version-conflict","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}