Halloween’s coming up, and it seems like a good time to remember all the moments of abject terror WordPress has brought into my life. Programming in WordPress is fun for the most part, but, especially as you’re learning, you’ll sometimes hit errors that are both incomprehensible and devastatingly severe. If you really need the site you’re working on to function properly, that can be an edge-of-your-seat experience.

Today we’ll take a look at probably the spookiest error of all: The WordPress White Screen of Death (WWSOD). Here’s what it looks like:

Yikes, right? Just like staring at a ghost.

Getting Information from the WWSOD

The major problem with the WWSOD is that it gives you no information.

The major problem with the WWSOD is that it gives you no information. In particular, the WWSOD is the result of some sort of (almost certainly PHP) error, but you’re not getting an error message that would let you understand the problem.

You’ll only see the WWSOD when your site’s server is configured not to display PHP errors. Many servers are configured this way, since users don’t like seeing ugly PHP errors and warnings, and since error messages can even compromise your site’s security by revealing how your filesystem is set up.

So our goal in solving our whitescreening problem is first to find an error message to inspect. Reading PHP error logs is one way to go, but for our purposes we’re going to examine the simplest option: getting error messages to display in-browser. Below, we’ll look at two ways of telling PHP to display error messages.

1. Enabling WP_DEBUG in wp-config.php

The quickest way to get errors to display is to edit your wp-config.php file. wp-config.php should be located in the root folder of your WordPress install—the same folder that holds your wp-admin, wp-content, and wp-includes folders.

You edit wp-config.php like you’d edit any other PHP file (for example, with a text editor), and the line you’ll want to change is this one:

define('WP_DEBUG', false);

It needs to change to this:

define('WP_DEBUG', true);

After you’ve made this change, save your changed wp-config.php back to its original location.

What Does This Do?

First things first, our WWSOD is now replaced by the following:

So, setting the WP_DEBUG global constant to true tells WordPress to enable a bunch of error displaying options that force PHP errors to show up in your browser—even if your server wouldn’t be displaying them otherwise.

With this error displaying, we know where to look: line 7 of the active theme’s (fifteenchild‘s) functions.php. And indeed, to create this error, I wrote some nonsense PHP into that line of the theme’s functions.php:

trouble = now;

2. For Fancy Folks: Editing php.ini

If you have enough access to and comfort with your server, you can get error messages to display by editing its php.ini file. This may be in a couple of places, so you’ll use a function called phpinfo() to find it. Once you’ve found it, you can edit it in your command-line tool (if you understand the command line), or use a text editor (if you’ve got good access to the server’s filesystem).

Inside php.ini itself, the main option to edit is called display_errors, which you can set to either On or Off. However, you can also set lots of other cool error-related things in this file. For example, with the error_log option, you can provide a path to a text file, and that file will then log all PHP errors the site generates.

My local server (the one on my private computer, set up with WAMP) even has an extension called Xdebug that makes error messages more readable and lets you trace the paths from which they were called. The Xdebug version of our initial error looks like:

You wouldn’t want this on a live site (since it lets everyone see the site’s internals), but it’s very helpful for debugging locally.

Other Notes on the WWSOD

Site-Wide (Including wp-admin) or Limited

Depending on where you’ve written your error, you can WWSOD your entire site—including the WordPress admin area (wp-admin)—or just a specific piece of your site.

Site-Wide

Remember, my sample error was in functions.php. That PHP file automatically runs for every page on the site. That means a full-site WWSOD, even for the admin area.

What’s really scary about this is if you’re using the admin area to make PHP changes using Appearance > Editor, and you don’t have a backup way (specifically FTP) to alter the affected files. If you write a buggy function to functions.php in the back-end, you can take down both the site and the tool you need to fix the site. In other words, Beware of the WordPress Appearance Editor!

Limited

Other changes, though, only take down certain sections of the site. Buggy code in page.php, for example, will only take down Page-type posts (like your site’s About page), because those are the only pages on the site that try to use the compromised code. Your admin area, for example, never uses page.php, so it’ll stay up no matter how buggy that file is.

So if you’ve ever wondered why some errors take down the whole site and some are limited, there’s your answer.

Halfway-Down-the-Page WWSODs

You may be wondering what’s up with pages that start out fine, and then just stop in the middle:

Again, turning debugging on (through WP_DEBUG, php.ini, or another method) clarifies this picture quite a bit:

This corresponds to a function I wrote midway through the code that builds out Page-type posts (like our About page). The function simply says:

trouble_time();

This function’s not defined anywhere, leading to the fatal error we’re seeing.

Now—why did we get part of a page first, and not a total whitescreen? This will happen when a couple of criteria are satisfied:

1. You write a PHP error that takes place partway through the PHP rendering of a page
2. The error’s not a “parse error”—PHP has no idea what you’re talking about because you wrote your syntax wrong—but rather an error that PHP can understand but doesn’t know what to do with. In this example, our syntax is right, but the function we’re asking PHP to go fetch doesn’t exist.

Thanks for the Spooks, WWSOD!

The WordPress White Screen of Death has given me a few good opportunities for soul-searching, and quite a few for sweat-soaked-shirt-changing. Hopefully today’s article will help you enjoy WWSOD events as a pleasantly spooky (but solvable) programming hiccup—the kind of thing that extends Halloween fun year-round—and not as a full bout of existential terror.

Thanks for reading!

Image credit: Ray Bodden