Beware the WordPress white screen of death

Mon Jun 14, 2010 8:03pm EDT

Woe to the WordPress administrator who finds only blank pages where once stood a WordPress-based blog or Web site. The site has been plagued with what an increasing number of WordPress operators are nicknaming the White Screen of Death.

As the nickname states, the White Screen of Death, WSoD, renders all the WordPress-built pages as a blank screen. But unlike the infamous Microsoft Windows Blue Screen of Death after which it was named, the WSoD does not offer any debugging code, or pointers to what might be causing the problem. Just a blank page where content once resided.

Worse yet, in addition to offlining a Web site or set of blog pages, the bug can also render invisible the WordPress Web-based administrator console, in which some debugging could occur.

The true cause of WSoD cannot be traced to any individual cause, or even to the WordPress code itself, but rather to a conflation of issues around the technology WordPress uses, as well as how the software is augmented by others.

"Our hands ... are mostly tied here, especially since WordPress is extended through code from others," said Andrew Nacin, a WordPress developer, in an e-mail interview.

The good news is that the developers of WordPress offer some simple hints at how to debug the problem, and they promise more measures to thwart the appearance of blank screens in the upcoming version 3.0 release of the software, which should be posted within a few weeks.

Since its first release in 2003, WordPress has played a pivotal role in the emergence of blogs on the Web. An open-source project, it is free to download, and Redwood City, California-based Automattic offers a hosted version of the blogging software, used by more than 291,000 participants.

Organizations are also considering using WordPress as a low-cost content management system.

WordPress is a modular program. It is actually built with other open-source tools, most notably the PHP Web scripting language. In order to construct a WordPress page, the Web server software executes a series of PHP scripts using a PHP processing module, drawing the content from a database, usually MySQL.

While the WordPress package offers the basic ability to run a blog, most of the additional functionality comes from plug-ins developed by third-parties. Likewise, the look-and-feel of a WordPress blog can be altered by using themes, or templates also generated by third parties.

Some of these of plugs-ins and themes are better constructed than others. And that's where the problem begins.

"Generally, you'll see [a blank page] when PHP hits a brick wall before the browser is served any output," Nacin said. "Some PHP errors will prevent any execution at all, including code that changes the setting."

This behavior seems to have perplexed many a WordPress administrator.

"HTML/CSS seem to be much more forgiving, whereas a single character of incorrect [PHP] seems to crash the whole site," wrote Amber Seeree, in one blog entry devoted to troubleshooting the issue.

Another developer got a white screen after inadvertently adding a single newline character to his configuration file. "You hit the Enter key in one wrong place and the whole pack of cards comes tumbling down!" wrote frustrated blogger Colin McNulty in 2008.

The WSoD can be triggered by any one of a number of issues, most all of them PHP-based, said Mark Jaquith, one of the lead developers for WordPress (Jaquith is not affiliated with Automattic).

White screens could be brought about by insufficient memory, a bungled configuration code, a problem with one of the plug-ins or themes.

Faulty plug-ins seem to be fault in many cases. And the way to find the faulty plug-in is requires some simple detective work.

Jaquith recommends renaming the "plugins" directory, which will deactivate all the plug-ins. If the site works after this, then the problem is a plug-in. At this point, the administrator can restore, one-by-one, each plug-in, until the faulty one is identified when the site crashes again.

The true aggravation of the WSoD comes not so much from any one specific error, but the lack of any immediate information about what has gone wrong. This is the way PHP handles errors, and it actually is, as the saying goes, a feature, not a bug.

PHP offers the option to display an error message on the affected page, though using this option is a bad idea for a number of different security reasons.

"The error message might reveal information about the server environment (like file paths) or information about what plug-ins are being run," Jaquith said. A Web site attacker could use such information to aid in an attack.

Writing error messages also requires granting write permission to publicly accessible files, another generally bad idea, Seeree pointed out.

Instead of having the server print the error message of the affected pages themselves, the administrator should look for the file in the system where PHP does log the errors, Jaquith advised. Most all server software will write error messages to a log file somewhere, as do most hosting systems like cPanel or Plesk.

Even though the cause of the WSoD lies outside of WordPress itself, WordPress developers are working to minimize its presence. For instance, WordPress checks for fatal PHP errors when activating a plug-in. If a fatal error occurs, the plug-in is sandboxed, meaning it is not activated until the problem is fixed.

The upcoming release of version 3.0 of WordPress will have even more measures to prevent blank screens, Jaquith said. For instance, this version will be the first to check for unexpected output when a plug-in is initialized. "This isn't a fatal error itself, but something unexpected that could cause fatal errors in certain situations," Jaquith said.

Another potential fix that version 3.0 will bring is that it may boost the memory limit for all actions executed by administrators. "Administrators are more likely to be doing things like upgrades that take more memory." Jaquith said.

WordPress is not the only Web software that can serve up the WSoD. The beta of Version 7 of the Drupal, another open-source content management system reliant on PHP, also suffers from the issue, said Adriaan BloemF, an analyst for the Real Story Group, a research and consulting firm specializing in content management software.

"WordPress and Drupal are particularly susceptible to this because users get to write PHP in templates and modules. Both systems are usually heavily customized, and the customizations are of varying quality," Bloem said.

Overall, however, this bug, despite the initial shock of seeing a WSoD is not a severe one, Bloem said. "The white screen is nothing to specifically worry about, it's just a PHP quirk," he said.

Bloem did add that as organizations rely more heavily on these software packages, they should make changes in a more controlled manner.

"Some of the more complex systems don't really allow developers to touch the core system that close, so they don't break as easily, or as catastrophically," Bloem said.