apache/maven · error · PluginParameterException

The parameters ${parameters} for goal ${mojo.getRoleHint()}

Error message

The parameters ${parameters} for goal ${mojo.getRoleHint()} are missing or invalid

What it means

The 'basic' component configurator finished populating the mojo and the parameter validator still found required parameters that were never assigned. Maven throws PluginParameterException listing each missing parameter name for the goal; its buildDiagnosticMessage() (printed by the default exception handler) even shows the exact <configuration> snippet to paste into the POM. A parameter is 'missing' when it is required, has no default-value, and receives neither a configuration value nor a usable -D property.

Source

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

            ConfigurationListener listener = new DebugConfigurationListener(logger);

            ValidatingConfigurationListener validator =
                    new ValidatingConfigurationListener(mojo, mojoDescriptor, listener);

            if (logger.isDebugEnabled()) {
                logger.debug("Configuring mojo execution '" + mojoDescriptor.getId() + ':' + executionId + "' with "
                        + configuratorId + " configurator -->");
            }

            configurator.configureComponent(mojo, configuration, expressionEvaluator, pluginRealm, validator);

            logger.debug("-- end configuration --");

            Collection<Parameter> missingParameters = validator.getMissingParameters();
            if (!missingParameters.isEmpty()) {
                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) {

View on GitHub (pinned to e4093d4e12)

Solutions

Read the message: it lists the missing parameter names; the diagnostic block printed with -e shows the exact XML to add.
Add the missing values under the goal's <configuration> (or plugin-level <configuration> if it applies to all executions).
If the parameter is bound to an expression like ${some.property}, pass -Dsome.property=... or define it in <properties>.
Run mvn help:describe -Dplugin=<g:a:v> -Dgoal=<goal> -Ddetail to list the required parameters of the exact version you use.
Verify the <configuration> block is not inside a profile that fails to activate.

Example fix

// before: required parameters 'outputDirectory' and 'resources' never set
<plugin>
  <artifactId>maven-resources-plugin</artifactId>
  <version>3.3.1</version>
  <executions>
    <execution>
      <id>copy-extra</id>
      <goals><goal>copy-resources</goal></goals>
    </execution>
  </executions>
</plugin>

// after: supply both required parameters for the execution
<plugin>
  <artifactId>maven-resources-plugin</artifactId>
  <version>3.3.1</version>
  <executions>
    <execution>
      <id>copy-extra</id>
      <goals><goal>copy-resources</goal></goals>
      <configuration>
        <outputDirectory>${project.build.directory}/extra</outputDirectory>
        <resources>
          <resource><directory>src/extra</directory></resource>
        </resources>
      </configuration>
    </execution>
  </executions>
</plugin>

Defensive patterns

Strategy: validation

Validate before calling

# list every required parameter of the exact goal/version before wiring configuration
mvn help:describe -Dplugin=org.apache.maven.plugins:maven-resources-plugin:3.3.1 -Dgoal=copy-resources -Ddetail \
  | grep -B3 'Required: true'

# confirm the values you intend to pass resolve to something non-null
mvn help:evaluate -Dexpression=project.build.directory -DforceStdout

Try / catch

// embedder: turn the exception into the fix it already knows
try {
    executor.execute(session, mojoExecution);
} catch (PluginParameterException e) {
    e.getParameters().forEach(p -> log.error('missing parameter: {} (expression: {})', p.getName(), p.getExpression()));
    log.error(e.buildDiagnosticMessage()); // prints the exact <configuration> snippet
}

Prevention

After any plugin upgrade, re-run help:describe -Ddetail: parameter names change between majors.
Keep goal configuration inside the <execution> that needs it so nothing is forgotten.
Confirm profiles carrying <configuration> are active in CI (mvn help:active-profiles).
Treat silently-ignored unknown <configuration> elements as a smell: compare against help:describe output.

When it happens

Trigger: Executing a goal whose required @Parameter(required=true) field gets no value: no <configuration> entry for the execution, the property it was tied to is unset, the config sits in a profile that is not active, or the parameter name is misspelled (unknown elements are silently ignored, so the real one stays null).

Common situations: Configuring a new goal invocation in <executions> and forgetting required children; plugin upgrade renaming a parameter; CI overriding a property with an empty value; copy-pasting examples written for a different plugin version.

Related errors

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