{"record":{"id":"f6a586420c3977de","repo":"apache/maven","slug":"a-required-class-was-missing-during-configuration","errorCode":null,"errorMessage":"A required class was missing during configuration of mojo ${mojoDescriptor.getId()}: ${e.getMessage()}","messagePattern":"A required class was missing 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":855,"sourceCode":"                message += \" for parameter \" + e.getFailedConfiguration().getName();\n            }\n            message += \": \" + e.getMessage();\n\n            throw new PluginConfigurationException(mojoDescriptor.getPluginDescriptor(), message, e);\n        } catch (ComponentLookupException e) {\n            throw new PluginConfigurationException(\n                    mojoDescriptor.getPluginDescriptor(),\n                    \"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    }","sourceCodeStart":837,"sourceCodeEnd":873,"githubUrl":"https://github.com/apache/maven/blob/e4093d4e120eac99d6bdce5ba67cace2f3085c97/impl/maven-core/src/main/java/org/apache/maven/plugin/internal/DefaultMavenPluginManager.java#L837-L873","documentation":"During mojo configuration (not mojo loading) a NoClassDefFoundError escaped: a class needed to convert or assign a configuration value — often the parameter's own type, a custom converter, or a type referenced by a setter — is missing from the plugin realm. Maven captures it, appends a realm dump, and throws PluginConfigurationException so you can trace which jar should contain the class.","triggerScenarios":"A mojo parameter's declared type lives in a dependency that was excluded or lost to mediation; a custom TypeConverter is not on the plugin classpath; a partially downloaded/corrupt jar in the local repository lacks the class file.","commonSituations":"Aggressive <exclusions> on the plugin; offline builds against a partially cached plugin; plugins whose parameter types come from a separate API artifact that was pruned; interrupted downloads leaving truncated jars.","solutions":["Take the class name from 'A required class was missing' and locate it in the realm dump: either the jar is absent or the local copy is broken.","Delete that artifact directory under ~/.m2/repository and rebuild with mvn -U to re-download cleanly.","Remove/relax exclusions on the plugin so the artifact carrying the parameter type returns.","Pin the needed library version under <plugin><dependencies> if mediation removed it.","Re-run with -X to inspect the full realm if the dump alone is unclear."],"exampleFix":"// before: corrupted jar in the local repo -> NoClassDefFoundError during configuration\n// (fix: remove the broken cached artifacts)\nrm -rf ~/.m2/repository/org/example/example-maven-plugin/1.0.0\n\n// after: force a clean, verified re-download\nmvn -U verify","handlingStrategy":"try-catch","validationCode":"# pre-flight: resolve plugins fully and remove truncated jars that break configuration-time classloading\nmvn -B dependency:resolve-plugins\nfind ~/.m2/repository -name '*.jar' -size -100c -print -delete\nmvn -U verify","typeGuard":"static boolean missingClassDuringConfiguration(PluginConfigurationException e) {\n    return e.getCause() instanceof NoClassDefFoundError;\n}","tryCatchPattern":"try {\n    executor.execute(session, mojoExecution);\n} catch (PluginConfigurationException e) {\n    if (e.getCause() instanceof NoClassDefFoundError ncdf) {\n        // message already contains the realm dump; name the jar that should hold ncdf.getClassName()\n        reportMissingJarForClass(ncdf.getClassName());\n    }\n    throw e;\n}","preventionTips":["Keep plugin dependency lists complete; do not prune transitive jars you did not analyze.","In CI, build once from an empty local repository to prove the plugin realm resolves from scratch.","Clean the plugin's local cache directory after failed or interrupted downloads.","Review realm dumps from -X output when adding new plugin dependencies."],"tags":["maven","plugin","classpath","noclassdeffounderror","configuration"],"backgroundTag":"missing-class-classpath","analyzedSha":"e4093d4e120eac99d6bdce5ba67cace2f3085c97","analyzedAt":"2026-08-21T22:58:24.034Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}