RSS Feed XML Declaration Error: Fixing Whitespace Before XML

Short answer: The error “XML declaration allowed only at the start of the document” means something is printed before the <?xml version="1.0"?> line of your RSS feed, usually a blank line, a space or a PHP notice. Strict XML parsers, including many feed readers and auto-posting tools, then reject the whole feed. Find the source by looking at the first bytes of the feed with curl, then remove the stray output, which in WordPress is most often a newline after a closing ?> in a theme or plugin file.

What the error actually means

An RSS or Atom feed is an XML document. The XML specification allows an optional declaration at the very top of the document, the familiar <?xml version="1.0" encoding="UTF-8"?> line. If it is present, it must be the first thing in the file. Not the second line, not after a space, not after an invisible character. When a parser meets the declaration anywhere else, it treats the document as malformed and stops.

The message looks different depending on the software reading the feed:

• Chromium-based browsers show “error on line 2 at column 6: XML declaration allowed only at the start of the document”.
• Firefox reports “XML Parsing Error: XML or text declaration not at start of entity”.
• Java-based tools often say “Content is not allowed in prolog” or “The processing instruction target matching [xX][mM][lL] is not allowed”.
• Feed validators flag it as a blank line or whitespace before the XML declaration.
• Auto-posting tools and feed readers may simply say the feed is invalid, cannot be parsed or has no items.

All of these describe the same problem: the feed does not start with the declaration. Note the “line 2” in the Chromium message. It is a strong hint that exactly one newline was printed before your feed began.

Why a single blank line breaks the whole feed

People are often surprised that one empty line can take a feed offline, because the feed may still look fine in some browsers and readers. The reason is that different programs handle broken XML differently. Some readers are lenient: they trim whitespace or fall back to a forgiving parser, so the feed appears to work. Others follow the XML rules exactly and refuse the document.

This makes the error confusing. Your own feed reader might display the feed normally, while an auto-posting service, a podcast directory or a news aggregator rejects it. The honest fix is not to hope that every consumer is lenient, but to make the feed well-formed so that every parser accepts it.

It also explains why the error often appears suddenly. Nothing changed in your posts, but a theme update, a new plugin or an edited configuration file added a stray line. From that moment, every strict consumer of the feed fails, and automated posting quietly stops.

Step 1: look at the first bytes of the feed

Before changing anything, confirm what is actually printed at the top. A browser is a poor tool for this, because it may reformat or hide whitespace. Use curl on the command line instead:

curl -s https://example.com/feed/ | head -c 200 | od -c | head

The od -c part shows each character, including invisible ones. A healthy feed starts with < ? x m l. If you see n first, there is a newline before the declaration. If you see spaces, a tab, or the three bytes 357 273 277 (the octal form of a UTF-8 byte order mark), you have found your culprit. If you see readable text such as “Warning” or “Deprecated”, PHP is printing an error message into the feed.

If you prefer hexadecimal, xxd works too:

curl -s https://example.com/feed/ | head -c 64 | xxd

Here a newline shows up as 0a, a carriage return as 0d, a space as 20 and a byte order mark as efbbbf. Also compare the feed with a normal page on the same site. If the homepage HTML also starts with a blank line, the stray output comes from code that runs on every request, which narrows the search considerably.

The most common causes

In practice, a handful of causes account for most cases:

1. A newline after a closing PHP tag. A PHP file that ends with ?> followed by an empty line prints that newline whenever the file is loaded. In WordPress, the usual suspects are the theme’s functions.php, a child theme file, a small custom plugin or wp-config.php.
2. Whitespace before the opening PHP tag. A space or empty line before <?php at the top of a file has the same effect.
3. A byte order mark in a PHP file. Some text editors save files with a UTF-8 byte order mark. In an included PHP file, those invisible bytes are printed as output before anything else.
4. PHP notices and warnings. If the server displays errors instead of logging them, a deprecation notice from an old plugin can land at the top of the feed.
5. Code that echoes output too early. A plugin that prints a tracking snippet, a comment or debug text on every request can end up in front of the XML.
6. Proxies or optimisation layers. Less often, a caching or minification layer injects content into responses it should leave alone.

Nearly all of these come down to the same thing: some code outputs characters before the feed template starts. The job is to find which file does it.

Step 2: find the file that prints the stray output

If you know what changed recently, start there. Otherwise, work through the site methodically. For WordPress, a reliable approach is:

1. Make a backup or use a staging copy of the site, so you can test without affecting visitors.
2. Check the feed with all plugins deactivated. If the error disappears, reactivate plugins one at a time and re-run the curl command after each. The plugin that brings the blank line back is the source.
3. Switch to a default theme temporarily. If the error disappears with a default theme, look at your theme or child theme, starting with functions.php.
4. Check wp-config.php. Look for any space or line before <?php and anything after a closing ?> at the end.
5. Search for byte order marks. On a server with shell access, grep -rl $'xEFxBBxBF' wp-content/ lists files that contain one, though you should confirm that the mark sits at the very start of a PHP file before editing.

If you have shell access, you can also check the last bytes of suspicious files with tail -c 20 functions.php | od -c. A file that ends in ? > n n is a classic cause. On other platforms such as a custom PHP site, the same logic applies: find the included files that run before the feed is generated and check their first and last bytes.

Step 3: fix it properly

Once you know the file, the fix is usually small:

• Remove the closing ?> from files that contain only PHP. The PHP documentation and common coding standards recommend omitting the closing tag at the end of pure PHP files precisely to prevent accidental output. Deleting the final ?> and any lines after it removes the problem permanently.
• Delete whitespace before <?php. The opening tag must be the very first characters of the file.
• Save files as UTF-8 without a byte order mark. Most code editors have an option for the encoding; choose the variant without BOM.
• Log PHP errors instead of displaying them. On a live site, error messages belong in a log file, not in pages or feeds. Turning off on-screen display and fixing the underlying notice keeps the feed clean.
• Update or replace the faulty plugin or theme. If the stray output comes from third-party code, report it to the developer and update when a fix is released. In the meantime, a small change in a child theme or a different plugin may be the safer option.

You will find snippets online that buffer all output and strip leading whitespace from the feed. They can work as an emergency patch, but they hide the real fault, and the same stray output may still break other responses such as sitemaps or API calls. Treat them as a temporary measure while you fix the source.

Step 4: clear caches and confirm the fix

After the fix, the old broken feed may still be served from a cache. Clear your page cache plugin, any server-side cache and your CDN cache for the feed URL. Then check again with curl, not the browser, and confirm the first bytes are <?xml.

Next, run the feed through the W3C Feed Validation Service. It will confirm that the declaration problem is gone and may point out other issues worth fixing at the same time, such as invalid dates or relative links.

Finally, check the tools that consume the feed. Feed readers and auto-posting services usually recheck on their own schedule, so the next check after the fix should succeed. If items were published while the feed was broken, look at whether they were picked up afterwards or whether you need to post them manually or with a catch-up option.

How to prevent it from happening again

• Adopt the no-closing-tag rule for every custom PHP file you or your developer write.
• Configure your editor to save UTF-8 without BOM and to show invisible characters.
• Test the feed after updates. After a theme or plugin update, a quick curl check of the feed takes seconds and catches the problem before it costs you missed posts.
• Monitor the feed. A simple uptime or content monitor that checks the feed URL and expects <?xml at the start will alert you the day it breaks rather than weeks later.
• Keep staging and production separate, so experiments with snippets and new plugins happen where a broken feed does no harm.

How PostRSS fits in

PostRSS reads your RSS or Atom feed every 5 minutes (every minute on Enterprise plans) and publishes new items to the networks you connect, 66 of them according to the features page. Like any tool that relies on the feed, it needs well-formed XML: if the feed cannot be parsed, new items cannot be detected until the feed is fixed. The PostRSS log shows each post and error, which helps you notice when something has changed at the source.

Once the feed is valid again, PostRSS picks up new items on its next check. If some posts were missed during the outage, the catch-up option lets you choose a start date so older items that were never published are posted as well. You can see how sources, targets and logs work on the PostRSS features page.

Related reading

• RSS Feed Validation: How to Make Sure Your Feed Works Before You Auto-Post
• RSS Feed Encoding Issues: Why Special Characters and Emoji Break Auto-Posts
• How to Recover From a Broken RSS Feed and Prevent Missed Posts

The bottom line

The XML declaration error is almost never about your content. It means some code prints characters, usually a single newline, before the feed starts. Look at the first bytes with curl, trace the output to the file that produces it, remove the closing PHP tag or the stray whitespace, clear caches and validate again. Ten minutes of careful checking brings a silent, broken feed back to life for every reader and every automation that depends on it.

FAQ

Why does my feed work in my browser but fail in other tools?

Some browsers and feed readers are lenient and ignore leading whitespace, while strict XML parsers reject the document. That is why the feed can look fine to you and still fail in an auto-posting tool or a directory. Checking the raw bytes with curl shows what strict parsers actually receive.

Is it safe to remove the closing ?> tag from a PHP file?

Yes, for files that contain only PHP code. The closing tag is optional at the end of a file, and leaving it out is a widely recommended practice because it prevents accidental output. Do not remove closing tags in the middle of template files that mix PHP and HTML.

Can a byte order mark cause this error?

It can. A byte order mark saved at the start of an included PHP file is printed as output, often together with other stray characters, before the feed begins. Save your PHP files as UTF-8 without BOM to avoid it.

Do I need to remove the XML declaration to fix the error?

No. The declaration is fine and useful; the problem is whatever comes before it. Remove the stray output so that the declaration is the first thing in the document.

Will my missed posts be published after I fix the feed?

It depends on the tool and on how many items your feed shows. Items still present in the feed are usually detected on the next check, while older items may need a catch-up option or manual posting.