Have you ever updated your site’s WordPress version or a theme or plugins only to be left with a blank white screen?
This is known as the “White Screen of Death” and it can spook some users into panic mode and even worse stop them from performing future site updates.
Thankfully it’s not as common as perhaps 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?
It’s usually caused by a PHP fatal error.
If you’re not a technical person you may now be wondering “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.
That’s the job of the webserver. 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 which 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, 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.
Sometimes a PHP function can be deprecated which means that either the function is no longer needed, 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 to first 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. */
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 on 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.
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 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 into 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 hosts 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 being 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 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 wasn’t the case then 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 now in this situation then 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.