apache/maven · error · XmlPullParserException

Unknown bean property: %s

Error message

Unknown bean property: %s

What it means

While PlexusXmlBeanConverter populates a bean from a sequence of XML elements, each element name is camelized (dashes stripped) and looked up among the bean's writable properties. An element that matches no property aborts parsing with an XmlPullParserException naming the offending element, which bubbles up as a conversion failure for the whole value.

Source

Thrown at compat/maven-embedder/src/main/java/org/eclipse/sisu/plexus/PlexusXmlBeanConverter.java:259

        final Object bean = newImplementation(clazz);

        // build map of all known bean properties belonging to the chosen implementation
        final Map<String, BeanProperty<Object>> propertyMap = new HashMap<>();
        for (final BeanProperty<Object> property : new BeanProperties(clazz)) {
            final String name = property.getName();
            if (!propertyMap.containsKey(name)) {
                propertyMap.put(name, property);
            }
        }

        while (parser.getEventType() == XmlPullParser.START_TAG) {
            // update properties inside the bean, guided by the cached property map
            final BeanProperty<Object> property = propertyMap.get(Roles.camelizeName(parser.getName()));
            if (property != null) {
                property.set(bean, parse(parser, property.getType()));
                parser.nextTag();
            } else {
                throw new XmlPullParserException("Unknown bean property: " + parser.getName(), parser, null);
            }
        }

        return bean;
    }

    /**
     * Parses an XML element looking for the name of a custom implementation.
     *
     * @param parser The XML parser
     * @return Name of the custom implementation; otherwise {@code null}
     */
    private static String parseImplementation(final XmlPullParser parser) {
        return parser.getAttributeValue(null, "implementation");
    }

    /**
     * Attempts to load the named implementation, uses default implementation if no name is given.

View on GitHub (pinned to e4093d4e12)

Solutions

1. Match the element name to an actual setter: use <maxRetries> or <max-retries> (both camelize to maxRetries)
2. Check the target class version for available setters if the config worked before an upgrade
3. Remove stale elements that no longer correspond to any property
4. Use the element name printed in the exception to locate the offending line in the XML

Example fix

<!-- before: element does not match any setter on the bean -->
<configuration>
  <maximumRetries>5</maximumRetries>
</configuration>

<!-- after: Plexus camelizes element names, max-retries/maxRetries map to setMaxRetries -->
<configuration>
  <max-retries>5</max-retries>
</configuration>

// Verify every element you plan to emit maps to a writable bean property
Set<String> writable = new HashSet<>();
for (java.beans.PropertyDescriptor pd
        : java.beans.Introspector.getBeanInfo(Server.class).getPropertyDescriptors()) {
    if (pd.getWriteMethod() != null) writable.add(pd.getName());
}
// emitting <max-retries>/<maxRetries> is safe only if writable.contains("maxRetries")
if (!writable.contains("maxRetries")) {
    throw new IllegalStateException("Server has no settable property 'maxRetries'");
}

try {
    Object bean = converter.convert(role, value);
} catch (IllegalArgumentException e) {
    if (e.getCause() instanceof XmlPullParserException xe
            && xe.getMessage().startsWith("Unknown bean property:")) {
        // xe.getMessage() names the offending element: fix or drop it in the XML
        log.warn("Bad element in config for {}: {}", role, xe.getMessage());
    } else {
        throw e;
    }
}

When it happens

Trigger: A <configuration> XML block where an element's camelizeName() has no matching BeanProperty setter on the target class, e.g. <maximumRetries> when the bean only defines setMaxRetries.

Common situations: Typos or wrong casing in plexus.xml/components.xml element names; component upgraded so a property was renamed/removed while old XML config kept; configuration copied from a different implementation class.

Related errors

• Cannot convert: "%s" to: %s
• Cannot read toolchains file at " + userToolchainsFile.getAbs
• Cannot create instance of: %s
• Cannot find '{}' in {}
• Only fully-qualified sets allowed in multiple set scenario:

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