XML declaration allowed only at the start of the document

What it means

The XML declaration must be the very first thing in the document — not one space and not one newline may come before it. This is stricter than the rule for content before the root element, where whitespace is allowed.

Because the offending bytes are invisible in most editors, this error is famously confusing: the file looks correct and still fails. If the leading bytes are printable text rather than whitespace you get "char is not expected" instead.

One nuance specific to XMLDir: a UTF-8 byte-order mark alone does not trigger this. Our validator tolerates a leading BOM, while Xerces and .NET reject it as content in the prolog — so a file that ingests cleanly here can still fail in a Java or .NET pipeline. Save without a BOM regardless.

What usually causes it

• A blank line or trailing whitespace before <?xml, often left by an include or a template.
• Output echoed before the declaration — a debug print, a warning, or a newline after PHP's closing ?> tag.
• Concatenating two XML documents, so a second declaration appears mid-file.
• A UTF-8 byte-order mark, which other parsers reject even though XMLDir accepts it.

How to fix it

• Remove all whitespace before the declaration; it must start at byte zero.
• Save as UTF-8 without BOM. In PowerShell prefer Out-File -Encoding utf8 over Set-Content's ANSI default.
• Check the first bytes directly: xxd file.xml | head -1.
• Omit PHP's closing ?> tag so a trailing newline cannot leak into the output.
• Never concatenate XML documents — merge their trees instead.

The same error elsewhere

Different parsers, same defect. If you arrived with one of these messages, you are in the right place.

• Xerces (Java)

  Content is not allowed in prolog.

• libxml2 (PHP, lxml, Nokogiri)

  XML declaration allowed only at the start of the document

• expat (Python)

  XML or text declaration not at start of entity: line 1, column 0

• .NET System.Xml

  Data at the root level is invalid. Line 1, position 1.