apache/maven · error · XMLStreamException

Unexpected namespace for element '%s': found '%s' but expect

Error message

Unexpected namespace for element '%s': found '%s' but expected '%s'

What it means

checkNamespace(parser, strict, namespace) runs for namespace-aware models: in strict mode each element's effective NamespaceURI must equal the namespace the generated parser carries (the model's target namespace), compared with Objects.equals. A null found-namespace is reported as 'no namespace'. It rejects documents in the wrong namespace - or none - before their fields are read.

Source

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

        ${classLcapName}.${field.name}(${field.name});
    #end
  #end
  #foreach ( $field in $allFields )
    #if ( $Helper.xmlFieldMetadata( $field ).format )
        ${classLcapName}.${field.name}($Helper.xmlFieldMetadata( $field ).format);
    #end
  #end
        return ${classLcapName}.build();
    }

 #end
#end

    private void checkNamespace(XMLStreamReader parser, boolean strict, String namespace) throws XMLStreamException {
        if (strict) {
            String ns = parser.getNamespaceURI();
            if (!Objects.equals(namespace, ns)) {
                throw new XMLStreamException(
                    String.format("Unexpected namespace for element '%s': found '%s' but expected '%s'",
                        parser.getLocalName(),
                        ns != null ? ns : "no namespace",
                        namespace),
                    parser.getLocation(),
                    null
                );
            }
        }
    }

    private String checkDuplicate(String tagName, XMLStreamReader parser, Set<String> parsed) throws XMLStreamException {
#set( $aliases = { } )
#set( $flats = { } )
#foreach( $class in $model.allClasses )
  #foreach ( $field in $class.getFields($version) )
    #set ( $fieldTagName = $Helper.xmlFieldMetadata( $field ).tagName )
    #if ( ! $fieldTagName )

View on GitHub (pinned to e4093d4e12)

Solutions

Add or correct the default namespace on the root element to the model's namespace URI (e.g. xmlns="http://maven.apache.org/POM/4.0.0").
Use a reader generated from the model version that matches the document's namespace.
For legacy non-namespaced documents, use the dedicated legacy reader or read with strict=false if acceptable.

Example fix

<!-- before -->
<project>
  <modelVersion>4.0.0</modelVersion>
</project>

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

Defensive patterns

Strategy: validation

Validate before calling

byte[] bytes = in.readAllBytes();
XMLInputFactory f = XMLInputFactory.newFactory();
XMLStreamReader peek = f.createXMLStreamReader(new ByteArrayInputStream(bytes));
while (peek.hasNext()) {
    if (peek.next() == XMLStreamReader.START_ELEMENT) break;
}
String ns = peek.getNamespaceURI();
peek.close();
if (!"http://maven.apache.org/POM/4.0.0".equals(ns)) {
    throw new IllegalArgumentException("Unexpected namespace: " + ns);
}

Type guard

static boolean isNamespaceMismatch(XMLStreamException e) {
    return e.getMessage() != null && e.getMessage().startsWith("Unexpected namespace");
}

Try / catch

try {
    Model model = reader.read(parser, true);
} catch (XMLStreamException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unexpected namespace")) {
        // document is in the wrong/absent namespace: route it to the right reader version
    }
    throw e;
}

Prevention

Pin document namespace versions and reader model versions together.
Validate the root namespace URI before strict reads.
Reject namespace-less XML early at intake.

When it happens

Trigger: Strict read of a document whose elements carry no namespace (e.g. a legacy Maven 1 project.xml), or whose namespace URI differs from what the reader's model declares (4.0.0 vs 4.1.0 style version skew between document and generated reader).

Common situations: Missing xmlns declaration on the root element; typo'd or outdated namespace URI; hand-written XML without namespaces; a document written for a newer model parsed by a reader generated from an older one.

Related errors

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