Common Gotchas
XML's rules are strict and mostly mechanical — which means the mistakes people make with it are, too. Here's the field guide to the ones that break real documents, in the order you're likely to actually hit them.
💡 The Bottom Line
Almost every broken XML document traces back to one of a handful of causes: a literal special character that wasn't escaped, a tag that wasn't closed or was closed in the wrong order, an encoding declaration that doesn't match the actual file bytes, or confusion between a document being well-formed (correct syntax) and valid (matches a required schema) — two different things people constantly conflate.
Gotcha 1: unescaped special characters
Five characters have special meaning in XML markup and must be escaped when they appear as literal data rather than as markup:
< for <
> for >
& for &
' for '
" for "The most common trap is a literal ampersand. A company name like "Johnson & Johnson"
written directly into an XML document breaks parsing, because the parser reads &
as the start of an entity reference like & or <, not as a
literal character:
<!-- NOT well-formed — bare ampersand -->
<company>Johnson & Johnson</company>
<!-- Well-formed — ampersand escaped -->
<company>Johnson & Johnson</company>⚠️ Gotcha 2: mismatched or unclosed tags
This is the single most common way a document fails to be well-formed — an opening tag with no matching close, or tags closed in the wrong order:
<!-- NOT well-formed — <author> never closes -->
<book>
<title>Dune</title>
<author>Frank Herbert
</book>
<!-- Well-formed -->
<book>
<title>Dune</title>
<author>Frank Herbert</author>
</book>Every parser will reject this outright — there's no ambiguity to fall back on, unlike HTML's more forgiving tag-soup handling.
Gotcha 3: the XML declaration and encoding mismatches
Many XML documents open with a declaration line stating the XML version and character encoding:
<?xml version="1.0" encoding="UTF-8"?>
<book>...</book>That encoding="UTF-8" is a promise to the parser about how to interpret the raw
bytes that follow. If the file was actually saved in a different encoding (say, Latin-1) but
still declares UTF-8, any characters outside plain ASCII — accented letters, curly quotes,
non-Latin scripts — can come out garbled or cause an outright parsing error, because the parser
is reading the bytes using the wrong rules. The declaration and the actual file bytes have to
agree.
⚠️ Watch Out
If you're generating XML programmatically, make sure whatever wrote the file actually used the encoding you declared — a mismatched declaration is a silent trap that often only surfaces later, when someone's name or a currency symbol renders as garbage.
Gotcha 4: confusing "well-formed" with "valid"
These sound similar but mean genuinely different things:
Well-formed
Follows XML's basic syntax rules — tags closed, properly nested, one root element, special characters escaped. This is purely about syntax.
Valid
Matches a specific schema or DTD that defines what elements, attributes, and structure are allowed for a particular document type. This is about conforming to someone's rules for this kind of document.
A document can absolutely be well-formed — perfectly correct XML syntax — while still failing validation, because it's missing a required element, has an element in the wrong order, or uses an attribute the schema doesn't allow. "It parses fine" and "it matches the schema we agreed on" are two separate questions, and mixing them up is a classic source of confusing bug reports ("but it's valid XML!" — well-formed, maybe; valid against the required schema, maybe not).
🙋 There Are No Dumb Questions
Q: If my document is well-formed, why would I still need a schema?
A: Well-formedness only guarantees the syntax is parseable — it says nothing about whether the
content makes sense for your application. A schema lets you say "a <book>
must have exactly one <title> and one <author>," which
well-formedness alone can never check.
🔧 Try It Yourself
Take this fragment and find both problems before checking your answer:
<item>Sold as Ben & Jerry's</item>. (Hint: it's about the ampersand
— what does a parser think comes right after it?)
✅ Quick Check
A document is well-formed but fails validation against its schema. What does that mean?
That's the whole track — time for the recap.