apache/maven · error · XMLStreamException

Unrecognised tag: '{}'

Error message

Unrecognised tag: '{}'

What it means

checkUnknownElement(parser, strict) is called when a child element matches no field of the class being parsed. Strict mode throws with the element's QName (parser.getName()). In lenient mode the same method silently skips the entire unrecognized subtree using a depth counter (unrecognizedTagCount via nextTag), so non-strict reads drop unknown content instead of failing.

Source

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

    private void checkUnknownAttribute(XMLStreamReader parser, String attribute, String tagName, boolean strict) throws XMLStreamException {
        // 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 {
        if (strict) {
            throw new XMLStreamException("Unrecognised tag: '" + parser.getName() + "'", parser.getLocation(), null);
        }

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

    /**
     * Method getTrimmedValue.
     *
     * @param s a s object.
     * @return String
     */

View on GitHub (pinned to e4093d4e12)

Solutions

  1. Fix or remove the unrecognized element - the message and location give its name and position.
  2. Upgrade the library so its generated model knows the element.
  3. Check spelling and casing against the model documentation.
  4. If unknown elements must be tolerated, read with strict=false - they and their 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 model read
SchemaFactory sf = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
Validator v = sf.newSchema(new StreamSource(xsdFile)).newValidator();
v.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")) {
        // tolerate unknown subtrees: re-parse leniently, unknown elements are skipped
        Model model = reader.read(new ByteArrayInputStream(bytes), false);
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: Strict read of documents containing elements unknown to the reader's model: a pom using a feature newer than the reader, misspelled tags like <dependencys>, or custom extension elements the model does not define.

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

Related errors

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