apache/maven · error · XMLStreamException

parser must be on START_ELEMENT to read next text

Error message

parser must be on START_ELEMENT to read next text

What it means

Internal guard in the Modello-generated reader's nextText helper (template src/mdo/reader.vm): reading an element's text body requires the StAX cursor to be positioned on START_ELEMENT. If the caller (or a previous parse step) advanced the cursor past the start tag, the reader throws javax.xml.stream.XMLStreamException immediately. End-user visible occurrences almost always mean malformed XML structure such as nested or mixed content where text was not expected.

Source

Thrown at src/mdo/reader.vm:1082

            int next = parser.next();
            switch (next) {
                case XMLStreamReader.SPACE:
                case XMLStreamReader.COMMENT:
                case XMLStreamReader.PROCESSING_INSTRUCTION:
                case XMLStreamReader.CDATA:
                case XMLStreamReader.CHARACTERS:
                    continue;
                case XMLStreamReader.START_ELEMENT:
                case XMLStreamReader.END_ELEMENT:
                    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(";");
                }

View on GitHub (pinned to e4093d4e12)

Solutions

1. Validate the document against the model's XML schema to find misplaced or nested elements at the reported location.
2. Fix or remove the misplaced child/text content so the element is a simple text node.
3. Regenerate the file with tooling matching the model version.
4. Ensure custom code is not sharing/reusing the XMLStreamReader instance across the generated reader and manual next() calls.

Example fix

<!-- before: nested element where model expects text -->
<name>commons-<vendor>apache</vendor>-lang</name>
<!-- after -->
<name>commons-apache-lang</name>

// schema- or structure-validate: scalar elements must have text-only content
if (elem.getChildren().size() > 0 && modelFieldIsScalar(elem.getName())) throw new IllegalArgumentException("nested content in scalar field: " + elem.getName());

try {
    reader.read(in, true);
} catch (XMLStreamException e) {
    if (e.getMessage().contains("START_ELEMENT to read next text")) { /* document structure mismatch: regenerate file */ }
}

When it happens

Trigger: A model XML document contains nested elements or stray text where the model expects a simple text node, desynchronizing the reader's cursor state; or client code drives the generated reader after manually advancing the same XMLStreamReader instance.

Common situations: POM/metadata documents with injected child elements into fields that are scalar in the model version being used; files transformed by naive string/XML tooling that moved tags around; version mismatch where a newer format nests elements the older reader treats as text.

Related errors

• TEXT must be immediately followed by END_ELEMENT and not {}
• Expected root element '${rootTag}' but found '{}'
• Duplicated tag: '{}'
• parser must be on START_ELEMENT to read next text
• TEXT must be immediately followed by END_ELEMENT and not {}

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