White screen of death after plugin activation

In this post, I’m talking about a specific type of failure after activating a plugin. There are numerous descriptions of how to solve different types of white screen failure at the end of this article.

What do we mean by the white screen of death

The error under discussion in this post occurs immediately after activating a plugin and you receive a message like the following:

The domainname.com page isn't responding
domainname.com is currently unable to handle this request
HTTP Error 500

After activation, your site is no longer accessible and panic ensues…

Quickly get the site back

As outlined in the articles listed below, the quick way to gain back access to your site is to FTP to your plugins folder and delete the plugin you’ve just installed. That should immediately restore your site. For information on how to fix the error, read on…

The error log is your friend

Luckily, when I encountered this problem recently with the Discussion Board Pro plugin, the error had been written to the error_log file that can be found in the root directory of the WordPress installation. This contained the following key piece of information:

[22-Mar-2017 02:48:35 UTC] PHP Fatal error:  Can't use function return value in write context in /home/accountname/public_html/wp-content/plugins/discussion-board-pro/inc/functions-boards.php on line 408

I was able to go straight to the file identified. There, I saw that I’d written the following conditional:

if( ! empty( ctdb_topic_board_id() ) ) {
  // Code here
}

The error message in the log clearly identifies that I shouldn’t have tried to incorporate a value returned directly from a function, i.e. from ctdb_topic_board_id(). PHP doesn’t want to let you use empty() or isset() on a function, it prefers you to use a variable.

What I needed to do was this:

$topic_board_id = ctdb_topic_board_id();
if( ! empty( $topic_board_id ) ) {
  // Code here
}

First I stored the value returned from the function in a variable. Then I checked whether the variable was empty. In other words, I didn’t wrap the function name inside the empty() check.

What happens if error_log offers no clue?

If you check error_log and there’s no helpful information there, then you’ll need to be more methodical in tracking down the bug.

As a first step, open the main plugin file to edit and comment out any actions and required files. Upload the file via FTP to the plugins directory and reload the site. Assuming the white screen error has been fixed (though you may have created a different error), you can begin to go methodically through each function call and required file, commenting them back in one by one, re-uploading and refreshing to test. As soon as you find where the problem occurs you can start to look for a fix.

PHP Versions

This error was only being thrown on PHP 5.4.xx. It might be that if you are using a different version of PHP you don’t see an error. The problem with this is that if you don’t test on different versions, you won’t necessarily spot errors before they get out into the wild. The Wisdom plugin is a useful tool here as you can use it to find out what versions of PHP are active on your users’ servers.

Articles on solving the white screen

If this particular case wasn’t helpful, you can try the following articles:

https://theme4press.com/wordpress-white-screen-death-causes-solutions/ – discusses various causes and solutions of white screens, including plugin incompatibility, WordPress version incompatibility, conflicts with other plugins, theme errors, PHP parse errors, and exceeding memory limits. It’s a really comprehensive article in that it takes you through a significant number of problems and solutions and provides options for troubleshooting.

https://codex.wordpress.org/Common_WordPress_Errors – the codex article on common WordPress errors. This offers a few more options to the article above.

https://thethemefoundry.com/blog/wordpress-white-screen-of-death/ – the consistently useful Theme Foundry blog offers some variations on possible causes.