How to fix common XML errors

Updated 19 November 2026 · 8 min read

XML parsers are deliberately strict: a single stray character makes the whole document unreadable, and the error message is not always clear. These are the problems behind most “not well-formed” errors, with examples of each and how to fix them.

Content before the XML declaration

If a document has an <?xml … ?> declaration, it must be the very first thing in the file. Even a single space or blank line before it is an error. This often happens when XML is pasted from an email or generated by a template.

✗ Invalid
  <?xml version="1.0" encoding="UTF-8"?>
<note>Hello</note>
✓ Valid
<?xml version="1.0" encoding="UTF-8"?>
<note>Hello</note>

Fix: Delete everything before <?xml, including whitespace and any byte-order mark added by a text editor.

HTML entities such as &nbsp;

XML defines only five named entities: &amp;, &lt;, &gt;, &quot; and &apos;. HTML entities like &nbsp;, &copy; or &rsquo; are undefined in XML.

✗ Invalid
<price>Rs.&nbsp;499 &copy; Shop</price>
✓ Valid
<price>Rs.&#160;499 &#169; Shop</price>

Fix: Replace HTML entities with numeric character references (&#160; for a non-breaking space), or with the actual characters in a UTF-8 document.

Unescaped & and < characters

In text and attribute values, & always starts an entity and < always starts a tag. Company names, URLs with query strings and comparisons are common culprits.

✗ Invalid
<company>Smith & Sons</company>
<link>/search?q=xml&page=2</link>
<rule>price < 100</rule>
✓ Valid
<company>Smith &amp; Sons</company>
<link>/search?q=xml&amp;page=2</link>
<rule>price &lt; 100</rule>

Fix: Escape & as &amp; and < as &lt;, or wrap large blocks of raw text in a CDATA section.

Mismatched or unclosed tags

Every opening tag needs a matching closing tag, and elements must close in the reverse order they opened. Unlike HTML, XML never closes tags for you.

✗ Invalid
<user><name>Asha</user></name>
<br>
✓ Valid
<user><name>Asha</name></user>
<br/>

Fix: Close inner elements first, and write empty elements as self-closing tags such as <br/>.

Tag names with different case

XML is case-sensitive, so <Name> and </name> are two different elements.

✗ Invalid
<Name>Asha</name>
✓ Valid
<name>Asha</name>

Fix: Use exactly the same spelling and case in the opening and closing tags.

More than one root element

A well-formed XML document has exactly one top-level element that contains everything else. Concatenating two documents or pasting a list of records breaks this rule.

✗ Invalid
<item>One</item>
<item>Two</item>
✓ Valid
<items>
  <item>One</item>
  <item>Two</item>
</items>

Fix: Wrap the elements in a single parent element.

Unquoted or duplicate attributes

Attribute values must be in single or double quotes, and an element cannot have the same attribute twice.

✗ Invalid
<img width=200 alt="logo" alt="brand"/>
✓ Valid
<img width="200" alt="logo"/>

Fix: Quote every attribute value and remove duplicates.

Unbound namespace prefixes

A prefix such as soap: or xsi: must be declared with an xmlns: attribute on the element or one of its ancestors. Copying only part of a SOAP message often leaves the prefix behind without its declaration.

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

Fix: Add the missing xmlns:prefix="…" declarations, using the namespace URIs from the original message or schema.

Invalid element names

Element and attribute names cannot start with a digit, hyphen or full stop, and cannot contain spaces. Names generated from spreadsheet column headers often break these rules.

✗ Invalid
<2024-total>500</2024-total>
<first name>Asha</first name>
✓ Valid
<total year="2024">500</total>
<first_name>Asha</first_name>

Fix: Start names with a letter or underscore and replace spaces with underscores or hyphens.

Broken CDATA sections and comments

A CDATA section ends at the first ]]>, so that sequence cannot appear inside it. Comments cannot contain a double hyphen --.

✗ Invalid
<code><![CDATA[ if (a[b[0]]> 1) ]]></code>
<!-- old value -- do not use -->
✓ Valid
<code><![CDATA[ if (a[b[0]]]]><![CDATA[> 1) ]]></code>
<!-- old value - do not use -->

Fix: Split a CDATA section around ]]>, and avoid -- inside comments.

Encoding mismatches

If the declaration says encoding="UTF-8" but the file was saved as Windows-1252 or ISO-8859-1, accented characters such as é or ñ become invalid byte sequences.

✗ Invalid
<?xml version="1.0" encoding="UTF-8"?>
<!-- file actually saved as Windows-1252 -->
<city>Bogotá</city>
✓ Valid
<?xml version="1.0" encoding="UTF-8"?>
<!-- file saved as UTF-8 -->
<city>Bogotá</city>

Fix: Save the file as UTF-8 (without changing the text), or change the declaration to match the encoding actually used.

Well-formed vs valid

Everything above is about being well-formed: following XML’s basic syntax rules. A document can be well-formed and still be invalid if it doesn’t match the schema (XSD or DTD) a system expects — for example a missing required element or a date in the wrong format. Fix well-formedness errors first; schema errors only make sense once the document parses.

Tip: Tagbrace shows the exact line and column of each XML error, and its Beautify and XML → JSON actions automatically fix the most common problems in this guide — leading whitespace, HTML entities, bare ampersands, missing namespace declarations and multiple root elements.

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

Open the formatter →