{"record":{"id":"a8b3be093b9751ce","repo":"apache/maven","slug":"an-api-incompatibility-was-encountered-while-execu","errorCode":null,"errorMessage":"An API incompatibility was encountered while executing ${mojoDescriptor.getId()}: ${e.getClass().getName()}: ${e.getMessage()}","messagePattern":"An API incompatibility was encountered while executing (.+?): (.+?): (.+?)","errorType":"exception","errorClass":"PluginExecutionException","httpStatus":null,"severity":"error","filePath":"impl/maven-core/src/main/java/org/apache/maven/plugin/DefaultBuildPluginManager.java","lineNumber":186,"sourceCode":"            mojoExecutionListener.afterExecutionFailure(\n                    new MojoExecutionEvent(session, project, mojoExecution, mojo, e));\n            ByteArrayOutputStream os = new ByteArrayOutputStream(1024);\n            PrintStream ps = new PrintStream(os);\n            ps.println(\n                    \"A required class was missing while executing \" + mojoDescriptor.getId() + \": \" + e.getMessage());\n            pluginRealm.display(ps);\n            Exception wrapper = new PluginContainerException(mojoDescriptor, pluginRealm, os.toString(), e);\n            throw new PluginExecutionException(mojoExecution, project, wrapper);\n        } catch (LinkageError e) {\n            mojoExecutionListener.afterExecutionFailure(\n                    new MojoExecutionEvent(session, project, mojoExecution, mojo, e));\n            ByteArrayOutputStream os = new ByteArrayOutputStream(1024);\n            PrintStream ps = new PrintStream(os);\n            ps.println(\"An API incompatibility was encountered while executing \" + mojoDescriptor.getId() + \": \"\n                    + e.getClass().getName() + \": \" + e.getMessage());\n            pluginRealm.display(ps);\n            Exception wrapper = new PluginContainerException(mojoDescriptor, pluginRealm, os.toString(), e);\n            throw new PluginExecutionException(mojoExecution, project, wrapper);\n        } catch (ClassCastException e) {\n            mojoExecutionListener.afterExecutionFailure(\n                    new MojoExecutionEvent(session, project, mojoExecution, mojo, e));\n            ByteArrayOutputStream os = new ByteArrayOutputStream(1024);\n            PrintStream ps = new PrintStream(os);\n            ps.println(\"A type incompatibility occurred while executing \" + mojoDescriptor.getId() + \": \"\n                    + e.getMessage());\n            pluginRealm.display(ps);\n            throw new PluginExecutionException(mojoExecution, project, os.toString(), e);\n        } catch (RuntimeException e) {\n            mojoExecutionListener.afterExecutionFailure(\n                    new MojoExecutionEvent(session, project, mojoExecution, mojo, e));\n            throw e;\n        } finally {\n            mavenPluginManager.releaseMojo(mojo, mojoExecution);\n            scope.exit();\n            Thread.currentThread().setContextClassLoader(oldClassLoader);\n            legacySupport.setSession(oldSession);","sourceCodeStart":168,"sourceCodeEnd":204,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/impl/maven-core/src/main/java/org/apache/maven/plugin/DefaultBuildPluginManager.java#L168-L204","documentation":"A LinkageError other than NoClassDefFoundError (typically NoSuchMethodError, AbstractMethodError, IllegalAccessError or IncompatibleClassChangeError) escaped a mojo execution. The plugin was compiled against one version of an API but the plugin realm supplies another: the classes exist, but their method signatures or access modifiers no longer match. Maven dumps the realm and rethrows everything as PluginContainerException inside PluginExecutionException.","triggerScenarios":"The plugin realm resolves a different version of a library than the one the plugin was compiled against, so a resolved method signature is missing or an abstract method is unimplemented. Classic cases: two versions of the same groupId:artifactId on the plugin classpath, or a plugin built against a newer Maven/plexus API than the running Maven provides.","commonSituations":"Upgrading Maven while keeping old plugin versions that need newer plexus/sisu APIs; dependency convergence failures pulling an older transitive version into the realm; libraries that changed signatures between minor versions.","solutions":["Take the incompatible class and method from the LinkageError message, then scan the dumped plugin realm for two artifacts with the same groupId:artifactId at different versions.","Pin the version the plugin expects in the plugin's <dependencies> so only one version lands in the realm.","Upgrade the plugin to a release built against the API version present in your build.","If the clash is with an API provided by Maven core itself, move to a plugin release compatible with your Maven version."],"exampleFix":"<!-- before: plugin release built for an older Maven line -->\n<plugin>\n  <artifactId>some-plugin</artifactId>\n  <version>1.2</version>\n</plugin>\n<!-- after: use the release built for your Maven version -->\n<plugin>\n  <artifactId>some-plugin</artifactId>\n  <version>2.3</version>\n</plugin>","handlingStrategy":"validation","validationCode":"mvn -Dmaven.plugin.validation=VERBOSE validate 2>&1 | tee /tmp/plugin-validation.log\ngrep -E 'incompatible|duplicate|excluded' /tmp/plugin-validation.log","typeGuard":null,"tryCatchPattern":"catch (PluginExecutionException e) {\n    Throwable c = e;\n    while (c.getCause() != null && !(c instanceof LinkageError)) c = c.getCause();\n    if (c instanceof LinkageError le) {\n        // le.getMessage() names the expected class/method: fix the realm, do not retry\n        log.error(\"binary incompatibility: {}\", le.getMessage());\n    }\n    throw e;\n}","preventionTips":["Upgrade plugins together with Maven upgrades, not independently","Check mvn dependency:tree output for duplicate groupId:artifactId pairs on plugin classpaths","Enable -Dmaven.plugin.validation=VERBOSE in CI to catch API-level mismatches before execution"],"tags":["maven","plugin","linkage-error","binary-compatibility","classpath"],"backgroundTag":"linkage-error-binary-incompatibility","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}