7 Mistakes that cause the WordPress White Screen of Death

Most seasoned WordPress developers have seen their share of the WordPress White Screen of Death. But that doesn’t diminish the nerve-wracking ordeal that you will be facing in the next few hours trying to fix this.

But what is this White Screen of Death?

In a production website it is a recommended best practice to turn off error messages. This is good because error messages can leak a surprising amount of information to hackers.

Yet, This is the reason for the White Screen of Death! It doesn’t display errors because they have been turned off!

Most common advice on solving this issue suggest reinstalling themes, deactivating plugins or increasing system limits.

Lets take a deeper look at the underlying causes of these errors. Understanding the causes can help you better debug this error when you encounter it again.

1. Infinite Loops

While plugins get blamed a lot for the White Screen of Death, it is actually WordPress Themes that are equally likely to be the source of this error.

Themes contain one of the most critical part of a WordPress site, The Loop. It is very easy to make an error or typo and have an infinite Loop.

WordPress Loops generally have the same exit clause, have_posts. But the incrementor of the Loop is the_post. If you forget the_post as below, you will have an infinite Loop. ie:- A Loop that never exists.

while (have_posts()):
  get_template_part('content', get_post_format());
endwhile;

If your theme does have an infinite loop, increasing memory limits or disabling plugins will have zero affect. All you will have achieved is a broken site that you now also need to rebuild.

Further, there are a number of places that themes use a Loop. So you could actually be using a Theme for a while and and not know about an infinite loop on your site. Unless you diligently check all different pages of your site, or a kind reader reports it to you, you won’t even know about the error!

Be careful in choosing your Theme and test it thoroughly.

2. Incorrect Syntax in wp-config.php

A typo in wp-config.php like forgetting or accidentally deleting the starting <?php tag is generally catastrophic for your site.

This is because WordPress hasn’t even managed to load yet. Debugging options like WP_DEBUG have no effect.

Likewise typos in any other core file like functions.php will be costly. How much information you will get, depends on what stage that file loads at.

This problem isn’t as bad for plugins. WordPress will auto-disable plugins with errors when you try to activate them. But if you start changing code in the Plugin Editor things can break easily.

Ensure that you don’t have syntax errors. Many code editors can do this automatically whenever you save a file. For Vim there is Syntastic which does this for a wide variety of languages including Javascript and CSS.

3. Fetching Unwanted Posts

This is another problem that occurs in Themes more than Plugins. It is also not easy to pick up on at the time of installation of a Theme. You will only notice it when your site starts growing bigger or if you already have a big site with a large database.

This is seen when a Theme limits the posts displayed on a page in the Loop when it should do so when it fetches. For instance a theme with a custom WP_Query with posts_per_page=-1 will fetch all posts in your database.

On a small blog the Theme will be fast enough, but a large site will grind to a halt on what might seem like a very simple page.

Don’t fetch Posts that you don’t need to display. Use pagination even in custom queries.

4. Invalid Function Syntax

These problems are commonly reported as whitespace issues. But they are really just invalid PHP syntax errors. In the function below, the closing brace is missing from the first function.

function gimme() {

function smores() {

}

These type of errors are the easiest to fix. Using a Syntax Checker will catch these errors before they become a White Screen of Death.

5. Plugin Incompatibility with WordPress Core

Plugin incompatibility can mean a wide variety of things. The simplest is incompatibility with a WordPress API function.

This usually happens when you update a Plugin that does not work with your WordPress version. Something innocuous like using is_tax instead of taxonomy_exists is not going to crash your site with a White Screen of Death.

But Plugins that override WordPress pluggable functions are good candidates that will break your site when versions don’t match. Caching is one frequent example. Using or upgrading a caching plugin that is not officially supported for your exact WordPress version is asking for trouble.

Be extra careful when upgrading Plugins that use pluggable APIs.

6. Incompatibility between Plugins

This happens when you bulk update a bunch of plugins. The upgrade was successful but now you have a White Screen of Death. Fortunately this is rare. Usually the incompatibility between versions will be documented or only cause some parts of your site’s layout to break.

For instance consider a Related Posts plugin that appends a list to the_content text. This plugin could be incompatible with an SEO plugin that uses the same the_content template tag for building HTML meta information. Yet this incompatibility would not bring about a White Screen of Death.

Regardless it can happen with minimal amount of code. In the code below the plugin is trying to exit early from a function, to prevent access to restricted content.

add_action('init', 'crash_my_site');
function crash_my_site() {
  if (!is_user_logged_in() || !is_something_allowed()) {
    die();
  }
}

Although contrived if this conditional is ever true, you’ll see the White Screen of Death. And it does so using hardly any resources.

Avoid bulk updates on a live site. If you must then test Plugin version compatibility locally before doing a bulk update in production.

7. Memory Exhaustion

If a Plugin or Theme uses too much memory, you may see the White Screen of Death. This depends on what stage the memory exhaustion occurs. If the code ran after some HTML was already flushed, you will only see a partial White Screen of Death!

This should also be a rare occurance on a well coded Plugin or Theme. Backup plugins can cause this error on large websites. But it could also be due to duplicating or sorting large arrays in memory. The following code simulates memory exhaustion by building a large array of strings.

$items = array();
for ($i = 0; $i < 2000; $i++) {
  $items[] = str_repeat($i, 100000);
}

On a system with a WP_MEMORY_LIMIT of 128M, you will quickly run out of RAM.

These kind of errors are quite difficult to debug. The piece of code that took you over the memory limit is rarely the source of problem. It's the code that took you to the brink of memory exhaustion that is the culprit.

A useful tool when debugging memory leaks is memprof.

The general idea with such memory profilers is to start wrapping potential weak areas with their sentry functions. Then dump memory usage profiles. Identify spikes and repeat this process until you have isolated the major spikes in memory usage.

Final Thoughts

The first order of business when you get a White Screen of Death is to turn on debugging. Thereby reducing it to a screen with at least some error messages.

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

The debug flags are a good start. But they still won't show any errors if you have an infinite loop. Then narrow down the list of possible issues one-by-one.

And if you do all this on a local development environment, the White Screen of Death will just be your little secret. :)

Level Up your WordPress-Fu with Weekly Tips in your inbox. Find out just why query_posts() is evil and why you should stop using it. (No Spam)

  • Philipp Stracker

    Thanks for the tipps!

    I also had a very curious case recently, where invalid file permissions did cause this error. My client did move the WordPress installation to a different server and as it seemed one core-file had wrong file permissions and could not be loaded (yep, this was really taking some time to find)

    I started editing wp-settings.php and added some “echo 1, 2, 3, …;”. Eventually I found the exact function call that caused the white screen and, when checking the file file that contained the function I noticed the invalid permissions… Possibly this was the only time I ever had this issue, but maybe someone else has an unexplainable error and this might help ;-)

    • Darshan Sawardekar

      Hi Philip,

      Yep! Invalid file permissions is another big one. Thanks for posting, I’m sure someone else will find this useful. :)

  • http://aprettierweb.com/ A Prettier Web

    I got a new one for ya!
    In serveral places I used <? instead of <?php and didn't have a problem locally and on several servers but then got blank screen when it hit that "<? " on one server that was more strict in its syntax!

  • Marty Smith

    Here is more bullet proof way how to enable wp_debug 4 ways how to fix white screen of death in wordpress