What causes "parser must be on START_ELEMENT to read next text" in apache/maven?

Create a fresh XMLStreamReader from buffered input for every read() call and leave it untouched before the call.

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

nextText(parser, strict), the generated helper for reading an element's text content, requires the parser to be positioned on that element's START_ELEMENT. Generated call sites only invoke it right after recognizing a start tag, so this invariant failure almost always means the parser handed to read() was in an unexpected state, or the STAX implementation misreports events.

Source

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

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

Create a fresh XMLStreamReader from buffered input for every read() call and leave it untouched before the call.
Do any pre-inspection with a separate parser over the same byte buffer.
Use the JDK default or Woodstox factory; check the classpath for conflicting javax.xml.stream implementations.

Example fix

// before: peek the root with the same parser, then reuse it
XMLStreamReader parser = factory.createXMLStreamReader(in);
while (parser.next() != XMLStreamReader.START_ELEMENT) { /* peek */ }
new MavenXpp3Reader().read(parser, true); // parser state is no longer fresh

// after: peek on a separate parser over buffered bytes
byte[] bytes = in.readAllBytes();
String root = peekRootLocalName(new ByteArrayInputStream(bytes));
Model model = new MavenXpp3Reader().read(new ByteArrayInputStream(bytes), true); // fresh parser

Defensive patterns

Strategy: try-catch

Validate before calling

// Prevention: buffer once, always hand read() a brand-new parser
byte[] bytes = in.readAllBytes();
XMLStreamReader parser = factory.createXMLStreamReader(new ByteArrayInputStream(bytes));
Model model = reader.read(parser, true);

Try / catch

try {
    Model model = reader.read(parser, true);
} catch (XMLStreamException e) {
    if (e.getMessage() != null && e.getMessage().contains("parser must be on START_ELEMENT")) {
        // parser misuse or broken STAX implementation, not bad input
        throw new IllegalStateException("parser handed to read() was not at its initial state", e);
    }
    throw e;
}

Prevention

Never hand read() a partially consumed parser; buffer input and create a fresh parser.
Keep pre-inspection and model reading on separate parser instances.
Standardize on one STAX implementation across the classpath.

When it happens

Trigger: Passing an XMLStreamReader already advanced beyond the initial document state (e.g. you peeked the root element yourself, then reused the same parser for read()); reusing one parser instance across reads; custom XMLStreamReader wrappers that drop or reorder events.

Common situations: Pre-inspecting documents with the same parser instance handed to the reader; filtering stream readers that swallow events; non-standard STAX providers picked up via ServiceLoader.

Related errors

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