apache/maven · error · XMLStreamException

Entities are not supported in strict mode

Error message

Entities are not supported in strict mode

What it means

The Modello-generated reader's nextText helper (src/mdo/reader.vm) encounters an ENTITY_REFERENCE event while reading element text and the reader is in strict mode. Only the five default XML entities are tolerated when addDefaultEntities is enabled; any other entity reference (e.g.  , ©, custom DTD entities) causes javax.xml.stream.XMLStreamException 'Entities are not supported in strict mode'. Non-strict mode substitutes known default entities or keeps the raw &name; text.

Source

Thrown at src/mdo/reader.vm:1092

                    return next;
            }
        }
    } //-- int nextTag(XMLStreamReader)

    private String nextText(XMLStreamReader parser, boolean strict) throws XMLStreamException {
        int eventType = parser.getEventType();
        if (eventType != XMLStreamReader.START_ELEMENT) {
            throw new XMLStreamException("parser must be on START_ELEMENT to read next text", parser.getLocation(), null);
        }
        eventType = parser.next();
        StringBuilder result = new StringBuilder();
        while (true) {
            if (eventType == XMLStreamReader.CHARACTERS || eventType == XMLStreamReader.CDATA) {
                result.append(parser.getText());
            } else if (eventType == XMLStreamReader.ENTITY_REFERENCE) {
                String val = null;
                if (strict) {
                    throw new XMLStreamException("Entities are not supported in strict mode", parser.getLocation(), null);
                } else if (addDefaultEntities) {
                    val = DEFAULT_ENTITIES.get(parser.getLocalName());
                }
                if (val != null) {
                    result.append(val);
                } else {
                    result.append("&").append(parser.getLocalName()).append(";");
                }
            } else if (eventType != XMLStreamReader.COMMENT) {
                break;
            }
            eventType = parser.next();
        }
        if (eventType != XMLStreamReader.END_ELEMENT) {
            throw new XMLStreamException(
                    "TEXT must be immediately followed by END_ELEMENT and not " + eventType /*TODO: TYPES[eventType]*/, parser.getLocation(), null);
        }
        return result.toString();

View on GitHub (pinned to e4093d4e12)

Solutions

  1. Replace named HTML entities in the XML with their literal UTF-8 characters or numeric references ( ).
  2. Remove any DOCTYPE/entity declarations from the model file.
  3. Read with strict=false (and addDefaultEntities enabled) if you must accept entity-laden documents.
  4. Sanitize upstream documentation before it is written into model XML.

Example fix

<!-- before -->
<description>Use&nbsp;this plugin</description>
<!-- after -->
<description>Use&#160;this plugin</description>
Defensive patterns

Strategy: validation

Validate before calling

static final Pattern NAMED_ENTITY = Pattern.compile("&[a-zA-Z][a-zA-Z0-9]*;");
static final Set<String> DEFAULTS = Set.of("amp", "lt", "gt", "quot", "apos");
boolean hasNonDefaultEntities(String xml) {
    Matcher m = NAMED_ENTITY.matcher(xml);
    while (m.find()) if (!DEFAULTS.contains(m.group().substring(1, m.group().length() - 1))) return true;
    return false;
}

Try / catch

try {
    reader.read(in, true);
} catch (XMLStreamException e) {
    if (e.getMessage().contains("Entities are not supported")) { // replace with numeric refs and retry
        String fixed = NAMED_ENTITY.matcher(raw).replaceAll(m -> numericRefFor(m.group()));
        model = reader.read(new StringReader(fixed), true);
    }
}

Prevention

When it happens

Trigger: Reading a POM or metadata file containing HTML-style entities such as &nbsp; or &eacute; in description/name elements with a strict reader. Note that standard predefined entities like &amp; and &lt; are resolved by the parser itself and do not trigger this; only entity references the parser reports as events (typically with a DTD or non-standard entities) do.

Common situations: Documentation text copied from HTML into <description>/<name> in pom.xml; files processed by tools that convert UTF-8 characters to named entities; custom entities defined via DOCTYPE in model files.

Related errors

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