Theme

Error explainers · XML

SAXParseException: Content is not allowed in prolog

The prolog is the part of an XML document before the root element: the optional <?xml ?> declaration, comments and a DOCTYPE. Text is not allowed there. The parser found characters before the first <, or a declaration that is not at the very start. Often the input is not XML at all, or something such as a header line, a BOM decoded with the wrong charset, or a file path ended up in front of it.

Seen as:

  • org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 1; Content is not allowed in prolog.
  • [Fatal Error] :1:1: Content is not allowed in prolog.
  • System.Xml.XmlException: Data at the root level is invalid. Line 1, position 1.
  • parser error : Start tag expected, '<' not found
  • The processing instruction target matching "[xX][mM][lL]" is not allowed.

Input

Settings

History

Load from URL

Common causes

1. Extra text before the document

A status line, a log prefix or response headers captured with the body put text in front of the XML. Pass the parser only the body.

Before
HTTP/1.1 200 OK
<invoice number="2026-091"/>
After
<invoice number="2026-091"/>

2. Whitespace or a blank line before <?xml

The XML declaration must be the very first thing in the file. Even a newline before it makes Java report that a processing instruction named “xml” is not allowed. Trim leading whitespace when generating the file.

Before

<?xml version="1.0" encoding="UTF-8"?>
<invoice number="2026-091"/>
After
<?xml version="1.0" encoding="UTF-8"?>
<invoice number="2026-091"/>

3. A byte-order mark read with the wrong encoding

A UTF-8 BOM decoded as Windows-1252 becomes the visible text “” before the declaration. Let the parser read the raw bytes (an InputStream rather than a Reader) so it can detect the encoding itself.

Before
<?xml version="1.0" encoding="UTF-8"?>
<invoice number="2026-091"/>
After
<?xml version="1.0" encoding="UTF-8"?>
<invoice number="2026-091"/>

4. The parser was given a file name or JSON instead of XML

Passing a path to a method that expects XML text (for example new StringReader("invoice.xml")) makes the parser read the path itself. A JSON error body from an API produces the same message.

Before
{"error": "invoice not found"}
After
<error>invoice not found</error>

Frequently asked questions

What exactly is the XML prolog?

Everything before the root element: the optional XML declaration, which must come first, followed by any comments, processing instructions and a DOCTYPE. Only markup and whitespace may appear there.

Why does the file look fine in my editor?

A BOM and some whitespace characters are invisible. Open the file in a hex viewer, or paste it into PasteKit, which reports the exact character and position before the root element.

How do I avoid this in Java?

Pass DocumentBuilder.parse a File or an InputStream rather than a String or Reader, so the parser handles the BOM and encoding declaration itself, and log the first bytes of any input that fails.

Related