XML namespace prefix not declared: how to fix it
“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.
<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:
| Where | Error message |
|---|---|
| libxml2 — xmllint, PHP, Python lxml, Chrome | Namespace 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.ElementTree | ParseError: unbound prefix: line 1, column 0 |
| Tagbrace validator | Element 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
- 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.
- Make a list of all prefixes used in the document — every
name:before an element or attribute name. - For each one, check there is a matching
xmlns:name="…"on that element or above it. Remember thatxml:(as inxml: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:
<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:
<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:
<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".
<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 prefix | Namespace URI |
|---|---|
soap (SOAP 1.1) | http://schemas.xmlsoap.org/soap/envelope/ |
soap / soap12 (SOAP 1.2) | http://www.w3.org/2003/05/soap-envelope |
xsi | http://www.w3.org/2001/XMLSchema-instance |
xs / xsd | http://www.w3.org/2001/XMLSchema |
xlink | http://www.w3.org/1999/xlink |
atom | http://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.
Related guides
- How to fix common XML errors
- How to convert SOAP XML to JSON
- JSON vs XML: key differences and when to use each
Check your own JSON or XML in seconds — free, and nothing is uploaded.
Open the formatter →