XML namespace prefix not declared: how to fix it

Updated 20 November 2026 · 6 min read

“Namespace prefix soap on Envelope is not defined”, “The prefix is not bound”, “'xsi' is an undeclared prefix” — every XML parser words it differently, but the cause is the same: a prefix is used without an xmlns: declaration. Here is how to find the missing prefixes and declare them correctly.

What the error means

In XML, a prefix like soap:, m: or xsi: is only a short name for a namespace URI. Before a prefix can be used, it has to be declared with an xmlns:prefix="URI" attribute on that element or on one of its ancestors. If the parser meets a prefix with no declaration in scope, it has no idea which namespace you mean, and it stops.

✗ Invalid
<soap:Envelope>
  <soap:Body>
    <m:GetPrice>
      <m:Item>Keyboard</m:Item>
    </m:GetPrice>
  </soap:Body>
</soap:Envelope>
✓ Valid
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:m="http://example.com/prices">
  <soap:Body>
    <m:GetPrice>
      <m:Item>Keyboard</m:Item>
    </m:GetPrice>
  </soap:Body>
</soap:Envelope>

Fix: add an xmlns: declaration for every prefix that is used — normally on the root element so it covers the whole document.

The error message in each tool

“Not declared”, “unbound” and “not defined” all mean the same thing:

WhereError message
libxml2 — xmllint, PHP, Python lxml, ChromeNamespace prefix soap on Envelope is not defined
Java (Xerces, JAXP)The prefix "soap" for element "soap:Envelope" is not bound.
.NET (XmlDocument, XDocument)'soap' is an undeclared prefix.
Python xml.etree.ElementTreeParseError: unbound prefix: line 1, column 0
Tagbrace validatorElement soap:Envelope prefix is unbound

The same error appears for attribute prefixes such as xsi:type or xsi:nil — the message then names the attribute instead of the element.

Find which prefixes are missing

  1. Paste the XML into the Tagbrace validator and click Validate. It reports the first unbound prefix with the line and column, and lists every undeclared prefix it found.
  2. Make a list of all prefixes used in the document — every name: before an element or attribute name.
  3. For each one, check there is a matching xmlns:name="…" on that element or above it. Remember that xml: (as in xml:lang) is built in and never needs declaring.

If you only need to read or tidy the XML, Tagbrace's Beautify and XML → JSON tolerate undeclared prefixes and tell you which ones they skipped over. Any strict parser receiving the file still needs the declarations, though.

Most common cause: a copied fragment

Declarations usually sit on the root element. When you copy just part of a document — the payload from inside a SOAP Body, a node from a log, one record from a big feed — the declarations stay behind on the parent you didn't copy:

✗ Invalid
<m:GetPrice>
  <m:Item>Keyboard</m:Item>
</m:GetPrice>
✓ Valid
<m:GetPrice xmlns:m="http://example.com/prices">
  <m:Item>Keyboard</m:Item>
</m:GetPrice>

Go back to the original document, find the xmlns:m="…" declaration on the element above, and copy it onto the root of your fragment.

xsi:nil and xsi:type without a declaration

The xsi: prefix appears everywhere in SOAP and schema-validated XML, and it is often missing when XML is written or edited by hand:

✗ Invalid
<order xmlns="http://example.com/orders">
  <discount xsi:nil="true"/>
</order>
✓ Valid
<order xmlns="http://example.com/orders"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <discount xsi:nil="true"/>
</order>

Default namespace is not the same as a prefix

A plain xmlns="…" sets the default namespace for elements without a prefix. It does not declare any prefix, so mixing the two fails:

✗ Invalid
<feed xmlns="http://www.w3.org/2005/Atom">
  <atom:title>News</atom:title>
</feed>

Either drop the prefix so the element uses the default namespace, or declare it separately with xmlns:atom="http://www.w3.org/2005/Atom".

✓ Valid
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>News</title>
</feed>

Common namespace URIs

The URI must be exactly right, character for character — http and https count as different namespaces. These are the standard ones:

Usual prefixNamespace URI
soap (SOAP 1.1)http://schemas.xmlsoap.org/soap/envelope/
soap / soap12 (SOAP 1.2)http://www.w3.org/2003/05/soap-envelope
xsihttp://www.w3.org/2001/XMLSchema-instance
xs / xsdhttp://www.w3.org/2001/XMLSchema
xlinkhttp://www.w3.org/1999/xlink
atomhttp://www.w3.org/2005/Atom

For a service's own prefixes, such as m:, ns1: or tns:, take the URI from the original message, the WSDL's targetNamespace, or the XSD. Don't invent one: a made-up URI makes the document well-formed, but the receiving service won't recognise the elements.

Avoiding it in code

When extracting part of a document in code, serialise the element with a namespace-aware library rather than slicing the text. lxml, for example, writes the declarations a fragment needs:

from lxml import etree

doc = etree.fromstring(soap_bytes)
ns = {"soap": "http://schemas.xmlsoap.org/soap/envelope/"}
payload = doc.find("soap:Body", ns)[0]

# lxml adds the xmlns declarations the fragment needs
print(etree.tostring(payload, pretty_print=True).decode())

In Java, make sure the parser is namespace-aware — DocumentBuilderFactory is not by default:

DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
f.setNamespaceAware(true);   // without this, prefixes are not resolved

And when generating XML, use your library's namespace APIs, such as createElementNS in the DOM or XmlWriter.WriteStartElement(prefix, name, ns) in .NET, instead of writing "<m:Item>" as a string. The library then declares each namespace for you.

Check your own JSON or XML in seconds — free, and nothing is uploaded.

Open the formatter →