XML guide
XML encoding declaration vs actual bytes
Diagnose XML that declares UTF-8 but arrives in another encoding, then repair the bytes, transport metadata, and declaration as one contract.
7 min read · Updated 2026-08-21
The short answer
The encoding declaration describes the bytes in the document; it does not convert them. Decode or transcode the source correctly, serialize the result in the chosen encoding, and make the XML declaration and HTTP Content-Type agree with those emitted bytes.Treat the declaration as a claim about bytes
A document beginning encoding="UTF-8" promises that the following byte stream is UTF-8. Relabeling Windows-1252 or ISO-8859-1 bytes does not transform them, so the parser eventually reaches a byte sequence that UTF-8 cannot decode.
<?xml version="1.0" encoding="UTF-8"?>
<customer>Zoë</customer>Identify the source encoding before decoding
Start with the raw response or file, not a string that an editor already decoded. Check a byte-order mark, the XML declaration, the HTTP charset parameter, and the producing system's documented export setting. When they disagree, preserve a sample of the original bytes for diagnosis.
- A UTF-8 BOM may identify UTF-8 but is not required.
- UTF-16 documents need byte order information and a matching declaration.
- An HTTP charset can participate in encoding detection for XML media types.
- Smart quotes and accented names are useful probes because ASCII alone hides mismatches.
Transcode once and align every label
Decode the original bytes using the real source encoding, then serialize a new byte stream in UTF-8 or another intentional target. Update the declaration and transport header to describe the output rather than the input.
Do not delete non-ASCII characters or replace every failed byte with a question mark. That makes the XML parse by losing data and prevents the producer-side defect from being found.
Get started
Bring order to the XML your team can't afford to ignore.
Create a free account and get a private workspace to search, validate, diff, and monitor your XML feeds, sitemaps, schemas, and vendor integrations.