apache/maven · error · PluginConfigurationException

Unable to retrieve component configurator ${configuratorId}

Error message

Unable to retrieve component configurator ${configuratorId} for configuration of mojo ${mojoDescriptor.getId()}

What it means

Maven tried to look up the component configurator named by the mojo's component-configurator hint and the container threw ComponentLookupException: no component is registered under that hint in core or in the plugin realm. Only the built-in 'basic' and map-oriented configurators ship with Maven; any custom hint (mapster, antiqua, groovy-aware configurators, ...) must be supplied by an artifact on the plugin's classpath.

Source

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

                } 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()
                    + ": " + e.getClass().getName() + ": " + e.getMessage());
            pluginRealm.display(ps);

View on GitHub (pinned to e4093d4e12)

Solutions

  1. Identify which artifact provides the configurator named in the message (check the plugin's documentation or its own POM).
  2. Add that artifact as a <dependency> inside the <plugin> block so it lands in the plugin realm.
  3. If the configurator is unnecessary (plain XML configuration), remove the <componentConfigurator> override from the plugin descriptor usage or use a plugin version that defaults to 'basic'.
  4. Verify the artifact is intact (contains META-INF/plexus/components.xml) and not a shaded stub.
  5. Upgrade the plugin family to a version that no longer needs the external configurator.

Example fix

// before: plugin descriptor uses <componentConfigurator>mapster</componentConfigurator> but nothing provides it
<plugin>
  <groupId>org.example</groupId>
  <artifactId>example-maven-plugin</artifactId>
  <version>1.0.0</version>
</plugin>

// after: add the artifact that registers the custom configurator as a plugin dependency
<plugin>
  <groupId>org.example</groupId>
  <artifactId>example-maven-plugin</artifactId>
  <version>1.0.0</version>
  <dependencies>
    <dependency>
      <groupId>org.codehaus.plexus</groupId>
      <artifactId>plexus-mapster-configurator</artifactId>
      <version>1.0</version>
    </dependency>
  </dependencies>
</plugin>
Defensive patterns

Strategy: validation

Validate before calling

# before adopting a plugin that uses a custom configurator, confirm its provider artifact is on the plugin classpath
mvn dependency:resolve-plugins
# then verify the artifact that documents the configurator is declared under <plugin><dependencies>
python3 - <<'EOF'
import xml.etree.ElementTree as ET
ns = {'m': 'http://maven.apache.org/POM/4.0.0'}
t = ET.parse('pom.xml')
for p in t.findall('.//m:plugin', ns):
    deps = p.findall('m:dependencies/m:dependency', ns)
    print(p.find('m:artifactId', ns).text, '->', [d.find('m:artifactId', ns).text for d in deps])
EOF

Try / catch

// embedder: distinguish 'configurator missing' from ordinary configuration failures
try {
    executor.execute(session, mojoExecution);
} catch (PluginConfigurationException e) {
    if (e.getCause() instanceof ComponentLookupException cle) {
        log.error('configurator {} not found: add its artifact as a plugin dependency', cle.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: A plugin's descriptor declares <componentConfigurator>custom</componentConfigurator> but the artifact implementing that Plexus ComponentConfigurator is not declared as a dependency of the plugin, its components.xml is missing (e.g., stripped by shading), or the hint is misspelled in the descriptor.

Common situations: Using Groovy/GMaven-style plugins that rely on mapster or similar configurators; relocating a plugin dependency that carried the configurator; plugin repackaged without Plexus metadata; copying a plugin block between projects whose dependencies section was dropped.

Related errors

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