What causes "Entities are not supported in strict mode" in apache/maven?

Replace named entities with numeric character references ( becomes ) or literal UTF-8 characters.

apache/maven · error · XMLStreamException

Entities are not supported in strict mode

Error message

Entities are not supported in strict mode

What it means

Inside nextText, an ENTITY_REFERENCE event in element text can only be honored in lenient mode, where DefaultEntitiesHolder substitutes the well-known HTML entities (nbsp, copy, ...). Strict mode refuses any entity substitution and throws, so content is never silently rewritten. Only the five predefined XML entities, resolved by the parser itself, survive a strict read.

Source

Thrown at src/mdo/reader-stax.vm:686

                    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 = DefaultEntitiesHolder.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

Replace named entities with numeric character references (  becomes  ) or literal UTF-8 characters.
Let a DOCTYPE-loaded DTD resolve the entities before the reader sees them, or restructure to avoid entities.
Parse with strict=false so DefaultEntitiesHolder substitutes the known HTML entities.

Example fix

<!-- before -->
<description>foo&nbsp;bar</description>

<!-- after -->
<description>foo&#160;bar</description>

Defensive patterns

Strategy: fallback

Validate before calling

// crude pre-scan: reject documents with non-predefined named entities before a strict read
String text = new String(bytes, StandardCharsets.UTF_8);
Matcher m = Pattern.compile("&([a-zA-Z][a-zA-Z0-9]*);").matcher(text);
while (m.find()) {
    if (!Set.of("amp", "lt", "gt", "quot", "apos").contains(m.group(1))) {
        throw new IllegalArgumentException("unsupported entity: &" + m.group(1) + ";");
    }
}

Try / catch

byte[] bytes = in.readAllBytes();
try {
    Model model = reader.read(new ByteArrayInputStream(bytes), true);
} catch (XMLStreamException e) {
    if (e.getMessage() != null && e.getMessage().contains("Entities are not supported")) {
        // lenient re-parse: DefaultEntitiesHolder substitutes the HTML default entities
        Model model = reader.read(new ByteArrayInputStream(bytes), false);
    } else {
        throw e;
    }
}

Prevention

Normalize named entities to numeric references at authoring time.
Keep rich text in CDATA or fully escaped form.
Choose strict vs lenient per content source, not per build.

When it happens

Trigger: Strict read of text containing a named entity beyond & < > " ' - e.g.   or © in a <description> - or custom entities declared in a DOCTYPE the parser did not resolve.

Common situations: HTML pasted into XML text fields; documents authored for lenient consumers then parsed strictly; DTD-reliant content read with DTD processing disabled.

Related errors

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