How to Troubleshoot the WordPress White Screen of Death (WSoD)
If you’re reading this, you’ve probably just found your WordPress site replaced by a big, white void of nothing. Poof!
Step one: don’t panic. What you have encountered is the infamous White Screen of Death (WSoD). While that moniker sounds intimidating, the reality isn’t as terrifying as you might imagine.
The fabled WSoD can occur when certain things go wrong with WordPress. Occasionally, some aspect of your site will be incomplete or damaged, which is what causes the white screen to appear in the first place. The problem often stems from an issue with your site’s PHP, which is the computer language WordPress is based on.
In this guide, we’ll dig deeper into the reasons why the White Screen of Death occurs, before showing you how to deal with it when it does. Let’s get started!
An Introduction to the White Screen of Death (WSoD)
The White Screen of Death (WSoD) is one of the most well-known WordPress errors. Most users have encountered this error at least once as it can be caused by numerous issues. As the name suggests, the WSoD is when you try to access your site, but it’s replaced with a plain white screen. This can occur on only part of your site or the entire thing plus your admin dashboard, depending on the underlying cause.
There are plenty of issues that can cause the WSoD to appear. Usually, an aspect of your site will be broken or incomplete in some way. The most common culprits are plugins and themes, which can contain incorrect code or cause a conflict with some other part of your site. The white screen can also appear due to a lack of memory or issues related to your hosting server.
Now, we don’t blame you if this error has you worried and confused. It may sound like just about anything could have caused your site to vanish. However, it’s not that difficult to troubleshoot and resolve the problem. We’re now going to demonstrate five troubleshooting techniques you can try to make your website reappear.
How to Troubleshoot the WordPress White Screen of Death (5 Techniques)
Since the WSoD presents you with a simple blank page, it can be difficult to diagnose the underlying cause. However, if you use the following techniques, you should be able to resolve the error quickly and painlessly. The techniques are sorted in order from the most to least common underlying issues, so you’ll want to start at the top and work your way down.
1. Test Your Plugins
What was the last thing you did on your site before it went blank? Chances are high that you recently activated, modified, or updated a plugin. Plugins are the most common culprit behind the WSoD error, so if you made changes to one lately, your first action should be to deactivate it. If you reload your site and everything is back to normal, you’ve already found the source of your problem. You should then contact the plugin’s developer, or log a ticket in its support forum for further assistance.
However, sometimes it’s not that easy. If you haven’t just added a new plugin, it’s still likely that one of your existing plugins is causing compatibility issues behind the scenes.How can you tell if this is the case, and figure out which plugin is to blame? The easiest fix is to disable all of your plugins. That way, if a plugin is not to blame, you will know as soon as you reload your site. You can then activate them again, and move on to the next step in the troubleshooting process.
You can deactivate all your plugins at the same time by going to the Plugins screen in your WordPress dashboard and using the Deactivate option in the Bulk Actions drop-down menu.
If you can’t access the admin interface, you can still do this via an SFTP client or your host’s file manager. All you need to do is to connect to your site using your SFTP credentials and then locate the folder called wp_content/plugins.
If you rename this folder to anything else, such as plugins_test, you’ll automatically disable all plugins (since WordPress won’t be able to locate them). When you want to reactivate them, simply change the folder name back to plugins.
If your site does start working again after you have deactivated your plugins, you can be pretty sure that one of them is at fault. What you need to do now is to re-enable them, one at a time, and test the site after each one is activated. This way, you can easily tell which plugin is broken, as the site will go back down as soon as you enable it. Then you can deactivate the faulty plugin again, and get in touch with the developers for further support.
If you’re using SFTP to perform your troubleshooting, you can do this by creating a new folder and naming it plugins. This will effectively make the folder your site’s plugin directory. All you need to do now is to move each plugin from plugins_test to this folder, which will reactivate it. Transfer each plugin one at a time, test your site to see if it works, and repeat the process until you find the one that’s broken. Just remember that you need to move all working plugins into the plugins folder when you’re done!
2. Investigate Your Theme
Just as plugins can contain outdated or incorrect code, so can themes. Some themes can be improperly coded, or cause a conflict with one or more of your plugins. There may have also been a problem with installing or updating the theme that has left it incomplete. Finally, if you’ve made changes to the theme’s functions.php file, that can also cause an error.
Fortunately, checking to see if your theme is causing the WSoD is simple. All you need to do is to disable it and revert to a generic theme instead. If you have access to the admin dashboard, you can do this by going to Appearance > Themes. Simply hover over one of the default WordPress themes, such as Twenty Seventeen, and click Activate.
If the admin dashboard is not available, you can also do this using SFTP. Open the wp_content/themes folder once again and simply rename the folder for the theme you are currently using.
This will cause WordPress to deactivate your theme, and automatically apply the default theme instead. You can now check your site to see if the WSoD is gone.
If this method fixes the problem, you know that your theme was the cause of the error. If you have recently made changes to the theme, you should try deleting it and reinstalling the original version. If this does not fix the problem, you’ll want to refer to the theme’s official documentation or reach out to the developer for more assistance.
3. Check Your Memory Limit
If the WSoD only appears occasionally or on certain parts of your site, it may be because your site has exceeded its maximum memory limit. This refers specifically to PHP memory, which is the amount of memory allocated to the PHP that WordPress runs on. The limit will usually be set to 64MB by default, but sometimes that’s not enough.
To fix this, you need to assign more memory to your installation. The exact way to do this can vary depending on your specific setup and host, but let’s cover some of the most common methods.
To increase your site’s PHP memory, you’ll usually need to edit a file on your server. For certain hosts, such as DreamHost, that is the php.ini file. If this file doesn’t exist on your site, you can create it via SFTP or Secure Shell Access (SSH). However, if you already have this file, you can access and edit it right now (also using SFTP or SSH).
All you need to do is add the following line anywhere in the file:
memory_limit = 100M
The number is the amount of MB you want to allocate to the PHP memory. It’s best to increase the memory limit by 10MB each time, and see if that resolves the problem. Since the standard limit for DreamHost is set to 90MB, this example starts at 100MB.
You’ll want to increase the memory limit by small amounts, and test the site each time you update the file. If your full site comes back online, you’ve resolved the problem!
However, you can only increase the memory limit by so much. Your site and installation will have a set maximum that you can’t exceed, so at a certain point you simply cannot keep bumping up the limit. If this occurs and you find that increasing the memory limit does not fix the problem, you might want to consider upgrading your current plan. It’s possible that shared hosting is no longer enough to support your site, for example, so refer to your host’s upgrade options to see if they match your requirements.
4. Use the WordPress Debug Mode
If you have come this far without finding the solution to your WSoD woes, it’s time to stop playing nice. It’s time we introduced you to the WordPress debug mode, which is a tool built into all installations of WordPress. Normally this is turned off because it’s strictly intended for testing purposes, but you can activate it at any time.
Activating the debug mode will create an error log of everything that happens when your site tries to load. You can even choose to display this information directly on the page. It’s recommended that you do this on a testing version of your site, as the information gathered by the debug mode can be sensitive. For example, it could contain personal information, or highlight security flaws.
To activate the debug mode, you’ll need to edit your site’s wp-config.php file. This file is a hugely important building block on your site, as it contains all your database information (including your passwords). You should, therefore, refer to the official documentation before you start editing it.
When you’re ready to start debugging, access your wp-config.php file through SFTP, SSH, or your host’s file manager. Look for the following line in the file’s code:
define( 'WP_DEBUG', false );
As we mentioned, this is set to ‘false’ by default. All you need to do is to change it to the following:
define( 'WP_DEBUG', true );
When you save the file, the debug mode will be activated. But how do you see the log it creates? You can display the debugging error log using one of two methods. The first is to generate a log file, which you can do by adding the following line to wp-config.php:
define( 'WP_DEBUG_LOG', true );
This will generate a file called debug.log in the /wp-content/ directory. This file can be opened and read using most standard text editors, such as TextEdit or Notepad.
You could also choose to display the error messages directly on the page. To do this, add the following code to wp-config.php:
define( 'WP_DEBUG_DISPLAY', true );
You can now check the HTML of your site to see the error log. The reason you’re doing this is that the log can give you an idea of what might be causing the WSoD to appear in the first place. If you’re lucky, the error log should make it clear exactly which file is causing the problem. For example, you may see an error like this one.
Parse error: syntax error, unexpected $end in /home/name/public_html/wordpress/wp-content/themes/your_theme/functions.php on line 231
In this case, you can see that the problem lies in the functions.php file, specifically on the line numbered 231. You can now open up the functions file, check the noted line, and investigate to see what could have caused the syntax error. As soon as you have corrected the problem, you can save the file and then check your site again.
If you get error messages that are less straightforward, you can usually enter them into Google or another search engine to find more information. It’s very rare that you’ll come across a truly unique problem, so somebody is likely to have faced — and solved — your specific issue before. You can also refer to the WordPress Codex and support forums for assistance.
When you have finished using the debug mode, it’s important that you remember to disable it. You can do this by once again editing the wp-config.php file, and changing the WP_DEBUG line back to false. Leaving this mode activated can lead to massive problems and security issues, so make sure to always close it down when you’re done troubleshooting.
5. Check Uncommon Errors
If you have made it this far and still haven’t been able to resolve your WSoD, you have our sympathies. You are also in the minority, as the techniques we’ve covered so far will resolve the vast majority of errors. However, there is still hope.
We’re now going to quickly run through some of the more uncommon issues that can cause problems with WordPress (resulting in the WSoD). These are less likely to be the cause but are not unheard of, so they’re important things to check if you’ve tried everything else already.
See If Your Server Is Down
It’s possible that your site’s issues could stem from your host server experiencing problems. The server could be down completely, so check other sites that you know are hosted on the same server. It’s also possible that certain aspects of the server are not functioning correctly, or are down for maintenance. One way you can check this is to review your host’s service status:
Even if your server seems to be fine and the host is not experiencing issues, you should still attempt to contact their support. Your site may still be experiencing troubles as a result of the server, even if nobody else is having the same problem. Therefore, they may be able to help you.
Check Your Caching Solution
Implementing a caching solution in WordPress is an excellent way of speeding up your site. However, because it saves old versions of files, there’s a risk that outdated content can cause problems.
This can be fixed by purging the cache, which will clear all that unnecessary stored data from your site. When you’ve done that, check your site again to see if you’ve fixed the problem. If so, you may want to contact the developers behind your caching solution to find out why the WSoD is happening, or get in touch with your host’s support team.
Investigate Your Site for Corrupted Files
It’s rare that WordPress’ core files get corrupted, but it can happen. For example, an error could occur when a new version of WordPress is installed, causing one or more of the files to be incomplete. When this is the case, you’ll usually see something in the error log created by the debug mode, but not always. If you suspect that there’s an issue with your site’s core files, you’ll want to contact your host and ask them to help you diagnose and fix the problem.
What to Do If Nothing Fixes the WSoD
In the unlikely event that the WSoD remains after you’ve performed all of the above troubleshooting techniques, it’s time to employ some last resort solutions. However, before you do anything else, you should first contact your host’s support team if you haven’t done so yet. In many cases, they will be able to help you out.
If you created a recent backup of your site when it was still working, you will have saved yourself a lot of trouble. A backup enables you to simply restore the earlier version of your site, which should hopefully reset whatever changes caused the WSoD to occur. How you restore your site will, of course, depend on your particular backup solution, host, and installation. When in doubt, refer to the official documentation and support services.
If you have no backup available, and your hosting provider can’t help, you will most likely have to install your site from scratch. This isn’t ideal, but it can be the only thing that will bring your site back to life. The process can take some time, but it’s important that you follow it to the letter to ensure that you don’t create any new errors along the way. When you’re done, your site should finally be up and running as normal.
Filling the Void
Having to deal with a malfunctioning website is never fun. However, it also doesn’t have to be a catastrophe. By properly troubleshooting the WSoD when it occurs, you should be able to identify the problem and resolve it quickly.
As we’ve discussed, there are several troubleshooting methods you can use to find the cause of the WSoD and fix it. Here’s a cheat sheet:
- Try deactivating your plugins. They’re the most common culprit so it’s essential to test them first.
- Replace your current theme with the default WordPress theme.
- Check your memory limit and increase it if possible.
- Use the WordPress debug mode to view your error log and look for the root cause.
- If all else fails, check to see if the server is down, if there are issues with your caching solution, or if you have corrupted files. You can also try restoring a backup of your site or contacting your web host for help.