How to fix the WordPress White Screen Of Death

Have you ever updated your site’s WordPress version, a theme, or a plugin, only to be left with a blank white screen?

This is known as the “White Screen of Death”, aka WSOD, and it can spook some users into panic mode and, even worse, stop them from performing future site updates.

In 2023 WordPress powers over 455 million websites. This means WordPress has a 42.7% market share of all websites.

Thankfully, the WSOD is not as common as the myth portrays, and it’s relatively simple to fix as long as you apply a method of figuring out where the problem lies.

What causes the white screen of death?

A fatal PHP error usually causes the White Screen of Death. 💀

If you’re not a technical person, you may now wonder, “What does he mean by that?”.

Let’s roll back and explain what that means.

When a WordPress post is displayed on a web browser to a site visitor, it has already gone on quite a little journey to get there.

PHP is a programming language that WordPress is (largely) built from. But a web browser doesn’t understand PHP – it only knows how to display HTML, CSS and Javascript.

When a WordPress post is displayed, the template from the theme associated with the post needs to be interpreted by PHP and rendered into HTML, CSS and Javascript for delivery to the browser.

That’s the job of the web server.  It takes the PHP from the theme template for the post and runs it through a PHP software interpreter on the server, which generates the HTML for the page so that it can be sent to the web browser.

Essentially it runs through each line of PHP code in the template line by line, running (interpreting) PHP functions that may come from your theme, installed plugins or WordPress itself, building up and outputting (rendering) this result to the browser.

If the PHP software interpreter tries to run a function that it doesn’t know about, this generates what is known as a PHP fatal error.  The PHP software interpreter then immediately stops processing any more of the template code, and a result of that is there is no HTML to send to the browser, hence a blank page!

It’s not the nicest way of handling things, but you have to remember PHP has been around for a long time, and even the creator of PHP didn’t think it would be used on this mass scale over the internet.

Why does PHP not know how to run that function?

The underlying reason is that the function is now missing.  Functions are PHP code snippets that perform an action and/or output a result, and they allow us to build complex themes, and plugins and make the WordPress software run as a Content Management System.

A function can go missing if 1) it is deprecated or 2) something went wrong with an update, and the actual PHP file with the function in it is missing from the webserver.

Deprecated Functions

Sometimes a PHP function can be deprecated, which means that either the function is no longer needed, or supported, or has been superseded/refactored into a separate function and removed from WordPress, a theme, a plugin or even PHP itself.

This happens regularly and it is up to the theme or plugin developer to actively support and update their code appropriately.

Missing PHP files

Everyone should update their WordPress themes and plugins regularly.  Usually, it all happens in the background with no issues, but sometimes there can be a problem.

The way that the WordPress updater works is first to download the new zip file for WordPress, the theme or the plugin, then it deletes the existing folder where WordPress, the theme, or plugin resides, and finally, it unzips the new directory and files.

Sometimes this process breaks if file permissions are not set correctly on the file system, or there are problems unzipping the newly downloaded zip file.

This can leave either a blank directory or a partially installed theme or plugin with missing files.

Of course, if PHP files are missing, then the corresponding functions are also missing and when something tries to call the missing function, PHP will return the fatal error call and stop processing and BOOM! – white screen of death!

How to find out where the problem is

There are a couple of ways of finding where the problem is.  Both methods require that you have access to the file system either using SSH or, more commonly, with File Manager in cPanel or your hosting company equivalent.

If your site is already in WSOD mode, then the only way you can fix it is to get access to the files on the server because you will not be able to access your site’s WordPress login screen.

One method requires you to update the wp-config.php WordPress configuration file.

If updating the configuration file scares you, there is an alternative method.

Method 1 – Switch on debugging

Putting WordPress into debug mode is the fastest way of finding exactly where the PHP problem is that’s causing the WSOD.  It will tell you the exact file and line number that is causing the error.

To switch on WordPress debugging, you will need to edit your wp-config.php file and add the following lines just above the line “/* That’s all, stop editing! Happy blogging. */“.

 // Enable WP_DEBUG mode
define( 'WP_DEBUG', true );

// Enable Debug logging to the /wp-content/debug.log file
define( 'WP_DEBUG_LOG', true );

// Disable display of errors and warnings 
define( 'WP_DEBUG_DISPLAY', false );

Once you have saved the file with the new lines added, go and refresh your site in the browser.  It will still have the WSOD, but this time WordPress has created a file called debug.log in your wp-content folder.

Open that file in your file manager and have a look at its contents.  There may be a lot of warnings and other stuff in there, but you’re looking for the line that contains PHP Fatal Error.

Here’s an example.

[15-Nov-2017 04:21:43 UTC] PHP Catchable fatal error:  Object of class stdClass could not be converted to string in C:\projects\wpdemo\www\wp-content\plugins\zpd-branding\zpd-branding.php on line 199

If you scroll along the line, you can see that the error originated in the ZPD Branding plugin at line 199 in the file zpd-branding.php

That’s pretty exact information!

Method 2 – Theme and Plugin Deactivation

If you’re not comfortable editing the WordPress configuration file, then this method usually works, but it is a little bit more time-consuming.

It’s the equivalent of the help desk “switch off then back on again” advice.

Assuming that WordPress core is not the issue, the idea is to see if the problem is first in your theme and then secondly to see if it is a plugin issue.

The first step is to switch your theme over to something like Twenty Seventeen.

If you can log in to your admin dashboard, then great – download Twenty Seventeen (if necessary), then activate it.

If you can’t log in to your dashboard, then you will have to use the cPanel File Manager or your host’s equivalent to move your theme’s folder out of wp-content/themes to wp-content.  Next, download the twenty seventeen zip file and upload it to your wp-content/themes folder.

Next, refresh the site in your browser, and it should pick up the twenty seventeen theme. If this is the case, then your site should load into the browser.  If it does, then it means there was something wrong with your current theme.

If you are still getting the WSOD after replacing your current theme with Twenty Seventeen, then it’s likely that the error is caused by a plugin.

Next, we have to deactivate or remove all the plugins and activate them one by one, refreshing the site in the browser after each one until you get the WSOD death again.  The last plugin you activated must then be the one that is causing the error.

If you have access to the admin dashboard, this process is easy, if a little time-consuming.

If you can’t access the admin dashboard of your site, then we again have to go in through cPanel and File Manager.

In this case, you want to move all the plugin folders out of the wp-content/plugins folder and then refresh your site in the browser.

It should work now as you have a vanilla WordPress install with Twenty Seventeen and no plugins.

Assuming this is the case, you use File Manager to move each plugin folder back into wp-content/plugins one by one refreshing your site in the browser each time until you get to the plugin that is causing the WSOD.

How to fix the white screen of death problem

Ok – if you followed the instructions above, you should have been able to ascertain which theme or plugin was causing the WSOD.  If that isn’t the case, you’ll have to go one step further back and reinstall WordPress on the site by unzipping the latest version from WordPress.org and redoing the methods outlined in the previous section.

Assuming you now know where the problem is, it should be a simple fix of replacing either the theme or the plugin with the original copy you purchased or from the WordPress.org repository.

If you turned on WordPress debugging, then now is the time to update your wp-config.php and set the debugging options to false or remove them completely.  Debugging is a great tool, but it slows down your site’s performance, so switch it off when you don’t need it.

White Screen of Death is still happening?

Oh, dear 🙁  That’s not good.  The above methods should have fixed it.

There may be some other reasons that your site is still not working.  These could be:

• Corrupted server files
• Malware infecting your site
• Server misconfiguration
• DNS issues

If you’re in this situation, the only way forward is to contact your hosting provider for some help.  They have access to server logs and should be able to either fix the issue or suggest a method going forward.

Most hosting companies will happily help you out through their support. However, if they back you into a corner and your site is still not working, then it may be time to call in some professional help.

Zero Point Development will be happy to consult with you to get your site back up and running.  We’ve dealt with some pretty banged-up sites to get them back up and running.

Have you ever encountered the White Screen of Death?

Tell us your story in the comments below.