For those of you who have never encountered the WordPress white screen of death, congratulations. For the rest of you, you know what a frustrating issue it can be. A blank white screen can lock you out of your WordPress dashboard, and make the public-facing side of your website look like a blank canvas. At first glance, it seems like all is lost, but don’t lose hope!
With new innovations in WordPress, like the Fatal Error Recovery Mode feature, white screens may soon become a thing of the past (or, at the very least, occur much less frequently than they once did). Until then, this article will show you the different things that may cause a white screen of death, how to identify the root cause, and how you can fix things once you know what’s going on.
Table of Contents
- What is the WordPress White Screen of Death?
- How “Fatal Error Recovery Mode” Is Changing the Game
- Troubleshooting for WordPress White Screen of Death
- Help! I’m Still Seeing a White Screen of Death!
What is the WordPress Blank White Screen of Death?
The white screen of death likely got its name from another screen that many of us remember.
In a lot of ways, the Microsoft blue screen and the WordPress blank white screen are the same. They both indicate that something has gone awry, and they can both probably both be fixed eventually. The main difference is that the WordPress white screen doesn’t show any error messages. Right off the bat that makes things more challenging to troubleshoot and debug, because you don’t have any additional information other than “the screen is white, so things must be broken”.
Think of the WSOD as a caution flag in a Nascar race. As the driver, you don’t know exactly what the problem is, but you know that you’re going to have to slow down and proceed cautiously for the next few laps in order to come out safe on the other side. Everyone has to slow down until the pieces are picked up, or the wrecked cars are returned to safety, but eventually, the green flag will come out again and everyone can get back to racing.
What Causes a WordPress White Screen of Death?
There are several factors that can contribute to a blank white screen of death, but it’s usually one of three things:
- An error being generated by a WordPress plugin
- An error being generated by your WordPress theme
- Some type of database error
The first two are the most common culprits, and definitely the easiest to diagnose as well.
What is Fatal Error Recovery Mode?
Thanks to an upcoming feature coined Fatal Error Recovery Mode, WordPress 5.2 will provide an avenue for logging into your site and resolving errors, even if your plugins or themes have code conflicts that historically would have brought a website to its virtual knees.
Felix Arntz of the WordPress core team explains what happens when Fatal Error Recovery Mode is triggered:
When a fatal error occurs, a user-facing error screen will display that informs the user/visitor that the site is experiencing technical difficulties. More importantly though, when such an error occurs, an email will be sent to the admin email address, informing about the issue and including a secret link to new feature called the “recovery mode”. Clicking this link will have the user enter this recovery mode, which works by placing a cookie on the current client.
In other words, WordPress will still be working just enough to send an email with a one-time link to access the admin area of the website. This link will be sent to the admin email in the General Setting panel in WordPress by default.
WordPress will also automatically “pause” any code that’s breaking your website. “Paused” is a new plugin status that lives somewhere between active and inactive. It tells you exactly where the fatal error lies so you know what needs to be fixed. The plugin will stay paused until it’s reactivated by a site admin.
Here’s a video overview of Fatal Error Recovery Mode (FERM) so you can see it in action:
When Fatal Error Recovery Mode Doesn’t Work
As of this writing, FERM is only available in beta versions of WordPress and should be included in WordPress 5.2 barring any unexpected setbacks. It’s also true that even when it’s included in WordPress core, it’s not guaranteed that all white screens will be eliminated forever.
For scenarios where FERM may not hit the mark, I’d like to offer some additional troubleshooting and diagnostic tips to help you resolve that dreaded WordPress white screen of death. This article is going to cover some of the most common steps you can take to troubleshoot and resolve that pesky white screen.
Troubleshooting for WordPress White Screen of Death
Before we get started with the actual troubleshooting process, it’s important to stop (remember the caution flag), take a deep breath, and start taking a few notes. Even if you end up hiring a WordPress support team (I know a pretty good one if you’re in the market) to fix your issue, these notes will come in handy.
4 Questions to Ask Before You Even Touch Your Website
- Have you upgraded any themes or plugins recently? Even a minor version upgrade can bring a site to it’s knees if the code hasn’t been properly vetted or tested for compatibility with WordPress or other plugins. That’s why we recommend testing any plugin upgrades in a staging environment if at all possible.
- Have you installed any new plugins on your site recently? When you install a new plugin, you’re adding a small (or large) block of code to your website that, if not properly tested, can generate a white screen on your site. For the most part, the plugin review team does a pretty good job to make sure plugins comply with certain coding standards, but it’s pretty much impossible to test all plugins together due to the sheer volume of plugins that exist. And that doesn’t even account for plugins that are purchased from third party sources like WooCommerce.com, CodeCanyon, or independent plugin shops.
- Have you installed a new theme recently? More often than not, the blank white screen of death is an issue with the front end of your site. If you’re able to access your WordPress dashboard, but the public facing view is showing white, there’s a good chance the issue is being caused by a theme conflict of some kind. If you’ve recently installed a new theme, you’ll know to look there to resolve the issue.
- Is your web host reporting any issues? Frequently your web host will report any known issues on a status page that they maintain, or through social media like Twitter or Facebook. If you’re looking for a new web host, that’s definitely a piece of information you’ll want to find early. How do they report known issues and where can you track them?
With this information in hand, you’re ready to start the troubleshooting process!
Tools You Need to Fix the WordPress Blank White Screen of Death in WordPress
To get started, you’re going to need a few tools that you may or may not already have.
- An FTP client – If you’re not sure what an FTP client is, you can read more about them here. Essentially it’s a “back door” way to access your website files directly since you may not have access through a web browser anymore. You can use FTP clients to transfer files to and from your web host. We really like Transmit ($45 and worth every penny), but it is Mac only. Filezilla works on Windows, Linux, and Mac, and is also free. Beware that you may end up with a few bonus programs that you weren’t planning on if you install Filezilla.
- A code editor – This may not end up being necessary, but can come in handy if there’s a code error that you need to debug. You can use a code editor to quickly identify syntax errors in plugin and theme code that you may not have seen otherwise. If you’re not comfortable even looking at code, you’ll probably want to contact professionals when you get to this point in the troubleshooting process. Atom has become a popular code editor of late, and is available for free on Windows and Mac. If you need a very basic code editor with no frills, Notepad++ works well for checking syntax.
Do you have access to WordPress admin?
One of the first things you need to identify is whether or not you can access
http://yourdomain.com/wp-admin/. If you’re getting a blank white screen on the admin pages as well, then the next steps are going to involve an FTP client. You can skip right to the section about how to troubleshoot if you can’t access wp-admin.
If you are able to access wp-admin, the length of this tutorial just got a whole lot shorter for you. You’ll be able to quickly eliminate the culprit using the information you took down earlier in the article.
- Deactivate any newly installed or upgraded plugins – The likely cause of your white screen is either a new plugin, or a recently upgraded plugin. If you’re able to login to your dashboard, navigate to the plugin screen and deactivate any plugins that were recently upgraded, installed, or changed.
- Deactivate all other plugins – This step can be a little tedious, but it is necessary. If step one didn’t resolve the white screen for you, you’ll need to go through your active plugins list and deactivate them one at a time until the issue is resolved. I recommend deactivating 1 or 2 at a time, and then checking the front end of the site to see if the white screen is gone.
- Change your theme – If after you’ve deactivated every plugin on your site, you’re still getting a white screen, the cause is going to be either the theme or the database. Troubleshooting database issues is the most involved step in this process, so your next step should be to change your WordPress theme to one of the default WordPress themes (TwentyNineteen, TwentySeventeen, etc).
- Look at server and caching configuration issues – This is an advanced step that we won’t go over much in this article, but once you’ve reached this point in the troubleshooting process and you’re still encountering the white screen of death, it’s probably time to contact your web host to see if they can see any issues occurring at the server level. This has become more common lately with advanced caching and server configurations from managed WordPress hosts. I know that the host we use, Pagely, has an option to clear out white screens from their hosting login, but that may not be typical of all hosts, and also has some unwanted consequences. If you’re using a caching plugin on your site, it may just require flushing your site’s cache for things to return to normal.
- Troubleshoot any possible database issues – This is another advanced step, but there likely are a few things you can check on your own before contacting your web host. A corrupt database may be what’s causing your white screen of death. This isn’t terribly uncommon, but you definitely want to proceed with caution before making any changes to the site’s database. Be sure that you have a recent backup of your site’s database before making any changes. We recommend a backup solution like BlogVault as it provides hourly backups and easier restores in the case that something goes wrong. Many hosts provide access to phpMyAdmin, which is a visual way to view your site’s database in your web browser. A2 Hosting has a nice article on how to repair your WordPress database via phpMyAdmin.
What if you don’t have access to WordPress admin?
This is where things really start to get fun. OK, maybe fun isn’t the perfect word here, but in a lot of ways, accessing the site via FTP can help you troubleshoot these issues even quicker than trying to do it through your web browser
Step 1: Disable All Plugins
Once you’re able to connect to your site using your FTP client, browse to the
/wp-content directory in your folder structure. It’s usually found inside a
htdocs folder. Inside the
/wp-content directory, you’ll see a
/plugins directory. This is where all of your plugin files are stored after they’ve been installed. You can actually disable all of your plugins by simply renaming the
plugins directory to
plugins.old. This will disable every plugin on your site, so proceed with caution, but that quick step will help you quickly identify whether plugins are the culprit or not. If renaming the folder makes the site visible again, you’ll know that there’s a plugin causing the problem.
To identify exactly which plugin is causing the issue, change
plugins.old back to
plugins, and then open that directory in your FTP client (as shown below). Then you can go through the same process for each individual plugin. By changing
pluginname.old, the individual plugin will be deactivated, and you’ll be able to check and see if your site is operational again.
This trial and error process will eventually help you identify which plugin is causing the white screen. Once you’ve identified it, you can delete the plugin using your FTP client. We have seen scenarios where the site only white screens if two specific plugins are active, so you may need to troubleshoot for a white to find out exactly which plugin or combination of plugins is causing the problem, but this method will narrow it down pretty quickly. This is one more reason why documenting any changes that are made to the site becomes critical. If you always know what you’re changing, you’ll easily be able to trace your steps back and resolve any issues that come up.
Another super helpful tool to help streamline this trial and error process is Plugin Detective. As long as you can upload the plugin to your WordPress site, it will automate the testing procedure for you by going through a troubleshooting wizard. Here’s a note from the plugin FAQ:
Detective Otto learns from you. While interrogating the different suspects, Otto will check in with you to see if the issue is still happening on your site or not. You just need to answer “Fixed” or “Broken” after Otto makes a change. Each of your answers provides Otto another clue that he is able to use to narrow down the list of plugins to find just the one that’s causing the problem.
Step 2: Deactivate your theme
There are a couple of different ways you can go about deactivating your WordPress theme. The quickest way is to ensure that you have one of the default WordPress themes installed in WordPress. Then if you rename your active theme the same way we renamed plugins, WordPress will automatically fall back to using a default WordPress theme.
For example, if my active theme name is
wpsitecare, and I also have
twentyfifteen installed on my site, if I rename
wpsitecare.old, WordPress will automatically activate
twentyfifteen since it’s a default WordPress theme.
The other option for changing your WordPress theme would be to access your database using phpMyAdmin, and browsing to your options table, and look for the
Again, changing any values in your database directly is a last resort, and should only be done if you understand all the ramifications, and have recent backups that you know how to restore.
By changing the
stylesheet values to
twentyfifteen and saving your changes, WordPress will use the TwentyFifteen theme instead of your previously active theme. In the majority of instances, as long as you’ve already gone through all of the other steps in this article, this step should resolve the WordPress white screen of death for you.
Step 3: Enable WP_DEBUG
For those of you who aren’t familiar with
WP_DEBUG, it’s a constant that you can add to your wp-config.php file on your website, that will output any specific errors that are occurring on the site the same way the Windows blue screen does.
WP_DEBUG, you’ll need to log in to the root of your WordPress site via FTP, the same way you did to disable plugins. You’ll probably want a code editor for this step just to make sure you can add the following code to your wp-config.php file without breaking more things.
define( ‘WP_DEBUG’, true );
define( ‘WP_DEBUG_LOG’, true );
define( ‘WP_DEBUG_DISPLAY’, true );
Above is an example of a wp-config file. The default for
WP_DEBUG is set to false (line 80 in the example above), but if you’re troubleshooting a white screen of death, you definitely want to change that value to true.
This isn’t going to resolve any of your issues, but it will provide some additional information that will help you sort things out.
After you change
WP_DEBUG to true, and save your wp-config.php file again, you’ll see error messages like the ones in the screenshot. At first, the messages may look like a foreign language, but you can pull out a few important parts. You’ll see the Genesis_Tabs text there, as well as plugin.php. This is indicating that it’s the Genesis Tabs plugin that’s causing your site to break. Deactivating that plugin or removing it from your site will fix your blank white screen of death.
Don’t forget to change WP_DEBUG back to false and save your wp-config.php file again. You don’t want to leave WP_DEBUG enabled on your live site if it isn’t needed for troubleshooting.
Is the White Screen Still not Fixed?
There are still a few other potential possibilities that we haven’t covered in the article, the majority of which are likely going to require the help of a professional team. Some other possibilities might be:
- Malware infection or hacked site
- Corrupted hard drive on the server
- Server misconfiguration, or server down
- DNS error or misconfiguration
If the approach in this article hasn’t resolved the issue for you, I’d recommend reaching out to your web host, or a team like ours to help debug this issue for you. We see this kind of thing regularly and have probably encountered your specific issue with some other client site.
If you don’t have the budget to hire a professional team, I can’t overemphasize the importance of maintaining regular backups that you have the ability to restore. If you’re still not able to fix the WordPress white screen of death after all of this, at the very least you’d be able to restore the site to a time when it was working properly.
Have you ever encountered the blank white screen of death? What ended up being the issue? Hit us up in the comments!