{"record":{"id":"0cba7669c1ce92ea","repo":"apache/maven","slug":"a-required-class-was-missing-while-executing","errorCode":null,"errorMessage":"A required class was missing while executing {}: {}","messagePattern":"A required class was missing while executing (.+?): (.+?)","errorType":"exception","errorClass":"PluginExecutionException","httpStatus":null,"severity":"error","filePath":"impl/maven-core/src/main/java/org/apache/maven/plugin/DefaultBuildPluginManager.java","lineNumber":176,"sourceCode":"            } catch (RuntimeException e) {\n                throw new PluginExecutionException(mojoExecution, project, e);\n            }\n        } catch (MavenException e) {\n            throw e;\n        } catch (PluginContainerException e) {\n            mojoExecutionListener.afterExecutionFailure(\n                    new MojoExecutionEvent(session, project, mojoExecution, mojo, e));\n            throw new PluginExecutionException(mojoExecution, project, e);\n        } catch (NoClassDefFoundError 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(\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);","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/impl/maven-core/src/main/java/org/apache/maven/plugin/DefaultBuildPluginManager.java#L158-L194","documentation":"Maven caught a NoClassDefFoundError while a mojo was executing: the plugin bytecode references a class that is not present in the plugin realm (the isolated classloader holding the plugin and its dependencies). Maven prints the missing-class message, dumps every artifact of the plugin realm into the error detail, wraps it in PluginContainerException and fails the build with PluginExecutionException.","triggerScenarios":"A mojo references a type whose jar is absent from the resolved plugin classpath: a transitive dependency was removed with <exclusions> inside the <plugin> declaration, an optional dependency of the plugin is not on the realm, the resolved dependency version no longer contains that class, or the jar in the local repository is truncated so the class entry is missing.","commonSituations":"Teams slimming plugin classpaths with exclusions; corrupted plugin jars after flaky downloads from a mirror; parent POMs pinning an older transitive library than the plugin expects; plugin dependencies relocated between versions.","solutions":["Read the error detail: it names the missing class and prints the plugin realm. Check whether the artifact that should contain the class is listed, and at which version.","If the artifact is absent or excluded, declare it explicitly inside the plugin's <dependencies> block (or remove the <exclusion> that dropped it).","If listed at the wrong version, pin the expected version in the plugin's <dependencies> so the realm converges on it.","If the jar may be corrupt, delete that artifact's folder under ~/.m2/repository and rebuild so Maven re-downloads it.","Reproduce with -X to watch the realm being assembled and confirm the fix."],"exampleFix":"<!-- before -->\n<plugin>\n  <groupId>org.codehaus.mojo</groupId>\n  <artifactId>exec-maven-plugin</artifactId>\n  <version>3.1.0</version>\n</plugin>\n<!-- after: explicitly add the dependency whose classes were missing -->\n<plugin>\n  <groupId>org.codehaus.mojo</groupId>\n  <artifactId>exec-maven-plugin</artifactId>\n  <version>3.1.0</version>\n  <dependencies>\n    <dependency>\n      <groupId>commons-cli</groupId>\n      <artifactId>commons-cli</artifactId>\n      <version>1.5.0</version>\n    </dependency>\n  </dependencies>\n</plugin>","handlingStrategy":"validation","validationCode":"# fail fast before the real build: force-resolution of all plugin classpaths\nmvn -q de.qaware.maven:go-offline-maven-plugin:2.10.0:resolve-dependencies || exit 1\n# surface realm problems early (Maven 3.9+)\nmvn -Dmaven.plugin.validation=VERBOSE validate 2>&1 | grep -i 'plugin'","typeGuard":null,"tryCatchPattern":"// embedded usage (maven-invoker / maven-embedder)\ntry {\n    InvocationResult r = invoker.execute(invocation);\n    if (r.getExitCode() != 0) failWithMissingClassReport(r);\n} catch (Exception e) {\n    Throwable c = e;\n    while (c.getCause() != null) c = c.getCause();\n    if (c instanceof NoClassDefFoundError nc) {\n        throw new IllegalStateException(\"plugin classpath is missing \" + nc.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Never put <exclusions> in a <plugin> block without executing the plugin once afterwards","Run CI builds with -Dmaven.plugin.validation=VERBOSE to get realm diagnostics before runtime","After network failures, verify freshly downloaded plugin jars with unzip -t before relying on them"],"tags":["maven","plugin","classloader","classpath","noclassdeffounderror"],"backgroundTag":"missing-class-on-classpath","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}