apache/maven · error · PluginConfigurationException

Unable to parse configuration of mojo ${mojoDescriptor.getId

Error message

Unable to parse configuration of mojo ${mojoDescriptor.getId()} for parameter ${e.getFailedConfiguration().getName()}: ${e.getMessage()}

What it means

While the configurator was populating the mojo, a configuration entry could not be parsed or converted into the parameter's declared type (ComponentConfigurationException). Maven wraps it in PluginConfigurationException, naming the mojo, the offending parameter (from getFailedConfiguration().getName()), and the underlying conversion problem. The value reached the mojo, but in the wrong shape.

Source

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

                if ("basic".equals(configuratorId)) {
                    throw new PluginParameterException(mojoDescriptor, new ArrayList<>(missingParameters));
                } else {
                    /*
                     * NOTE: Other configurators like the map-oriented one don't call into the listener, so do it the
                     * hard way.
                     */
                    validateParameters(mojoDescriptor, configuration, expressionEvaluator);
                }
            }

        } catch (ComponentConfigurationException e) {
            String message = "Unable to parse configuration of mojo " + mojoDescriptor.getId();
            if (e.getFailedConfiguration() != null) {
                message += " for parameter " + e.getFailedConfiguration().getName();
            }
            message += ": " + e.getMessage();

            throw new PluginConfigurationException(mojoDescriptor.getPluginDescriptor(), message, e);
        } catch (ComponentLookupException e) {
            throw new PluginConfigurationException(
                    mojoDescriptor.getPluginDescriptor(),
                    "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()

View on GitHub (pinned to e4093d4e12)

Solutions

Note the parameter named in the message and check its declared type via mvn help:describe -Dplugin=<g:a:v> -Dgoal=<goal> -Ddetail.
Fix the value so it converts: correct casing for enums, true/false for booleans, numeric text for numbers.
Align the nested element structure with the parameter object's fields (or the version's new structure after an upgrade).
If the value comes from ${...}, run mvn help:evaluate -Dexpression=<expr> -DforceStdout to see what it resolves to.
Run mvn help:effective-pom to confirm the final configuration Maven actually received.

Example fix

// before: value does not convert to the boolean parameter 'enabled'
<configuration>
  <enabled>3</enabled>
</configuration>

// after: value matches the declared parameter type
<configuration>
  <enabled>true</enabled>
</configuration>

Defensive patterns

Strategy: validation

Validate before calling

# know the declared type before passing a value
mvn help:describe -Dplugin=<groupId>:<artifactId>:<version> -Dgoal=<goal> -Ddetail | sed -n '/<parameterName>/,/Type/p'

# see the final configuration Maven will receive
mvn help:effective-pom -Doutput=/tmp/eff.xml && grep -A6 '<parameterName>' /tmp/eff.xml

Try / catch

// embedder: surface which element failed conversion
try {
    executor.execute(session, mojoExecution);
} catch (PluginConfigurationException e) {
    if (e.getCause() instanceof ComponentConfigurationException cce
            && cce.getFailedConfiguration() != null) {
        log.error('bad value for <{}>: {}', cce.getFailedConfiguration().getName(), cce.getMessage());
    }
    throw e;
}

Prevention

Match value shape to the parameter type declared in help:describe -Ddetail (enum casing, booleans as true/false).
After plugin upgrades, re-read the parameter docs: simple values sometimes become structured objects.
Check expressions with help:evaluate before embedding them in typed parameters.
Lint the effective POM in CI for configuration elements unknown to the plugin version.

When it happens

Trigger: XML text that cannot convert to the field type: non-numeric text for an int/double parameter, a value not in the parameter's enum, a malformed File path list, a ${...} expression evaluating to a value of the wrong shape, or nested child elements that do not match the parameter object's setters.

Common situations: Passing '3' to a boolean parameter; enum parameter values with wrong casing; expression returning an empty string where a number is required; plugin upgrade changing a parameter from a simple string to a structured object; wrong nesting depth in <configuration>.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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