apache/maven · error · XMLStreamException

Unrecognised tag: '{}'

Error message

Unrecognised tag: '{}'

What it means

checkUnknownElement in the classic reader.vm template: a child element matching no field of the parsed class throws in strict mode with the element's local name. In lenient mode it skips the whole unrecognized subtree with a depth counter driven by parser.next() (the stax variant uses the nextTag helper instead) - same effect: non-strict reads drop unknown content instead of failing.

Source

Thrown at src/mdo/reader.vm:718

        // strictXmlAttributes = true for model: if strict == true, not only elements are checked but attributes too
        if (strict) {
            throw new XMLStreamException("Unknown attribute '" + attribute + "' for tag '" + tagName + "'", parser.getLocation(), null);
        }
    } //-- void checkUnknownAttribute(XMLStreamReader, String, String, boolean)

    /**
     * Method checkUnknownElement.
     *
     * @param parser a parser object.
     * @param strict a strict object.
     * @throws XMLStreamException XMLStreamException if
     * any.
     * @throws IOException IOException if any.
     */
    private void checkUnknownElement(XMLStreamReader parser, boolean strict)
        throws XMLStreamException, IOException {
        if (strict) {
            throw new XMLStreamException("Unrecognised tag: '" + parser.getLocalName() + "'", parser.getLocation(), null);
        }

        for (int unrecognizedTagCount = 1; unrecognizedTagCount > 0;) {
            int eventType = parser.next();
            if (eventType == XMLStreamReader.START_ELEMENT) {
                unrecognizedTagCount++;
            } else if (eventType == XMLStreamReader.END_ELEMENT) {
                unrecognizedTagCount--;
            }
        }
    } //-- void checkUnknownElement(XMLStreamReader, boolean)

    /**
     * Returns the state of the "add default entities" flag.
     *
     * @return boolean
     */
    public boolean getAddDefaultEntities() {

View on GitHub (pinned to e4093d4e12)

Solutions

  1. Fix or remove the unrecognized element - message and location give name and position.
  2. Upgrade to a library version whose model knows the element.
  3. Check spelling/casing against the model docs.
  4. Read with strict=false when unknown elements must be tolerated (subtrees are skipped).

Example fix

<!-- before -->
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <dependencys>...</dependencys>
</project>

<!-- after -->
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <dependencies>...</dependencies>
</project>
Defensive patterns

Strategy: fallback

Validate before calling

// XSD validation reports unknown elements before the strict read
SchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
sf.newSchema(new StreamSource(xsdFile)).newValidator().validate(new StreamSource(xmlFile));

Type guard

static boolean isUnknownElement(XMLStreamException e) {
    return e.getMessage() != null && e.getMessage().startsWith("Unrecognised tag");
}

Try / catch

byte[] bytes = in.readAllBytes();
try {
    Model model = reader.read(new ByteArrayInputStream(bytes), true);
} catch (XMLStreamException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unrecognised tag")) {
        // tolerated: lenient re-parse skips unknown elements and their subtrees
        Model model = reader.read(new ByteArrayInputStream(bytes), false);
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Strict read of documents with elements unknown to the reader's model: newer-schema features with an older reader, misspelled tags, custom extension elements.

Common situations: Version skew between document and generated reader; hand-editing typos; third-party tools injecting proprietary elements.

Related errors

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