Section 1 – An Overview
There’s few things more frightening to a WordPress site owner than an entirely blank screen:
- No one visiting can see your site.
- Nothing works at all.
- You can’t even access the admin area to fix it!
This is known as the “White Screen of Death” (WSOD). It’s a play on the phrase “Blue Screen of Death” which refers to Microsoft Windows crashing so badly only a reboot gets things working again.
So, if the dreaded WSOD hasn’t happened to you yet – great! But, if you use WordPress for long enough, sooner or later you’re likely to come across it. In fact, it happened to me last week when working on a client’s site. Here’s what happened in my case…
The client’s site was working well overall. This particular client offers training and runs events, and to date members can only pay annually, and then get updates sent to them by email. So I’m in the process of adding a member area that ideally supports:
- Monthly and annual billing, as well as being able to offer trial periods.
- Automatically gives the customer access once they’ve paid.
- Automatically adds the new member to the CRM so they also receive relevant follow-ups.
- Automatically removes a membership account when someone cancels (at the end of their billing period of course).
- Along with other useful functionality including an affiliate program for members.
Now, there’s plenty of great membership software options for WordPress, and I started narrowing the list down and had a couple in mind to test out. But – with one of these plugins, as soon as it was activated, it took the site offline completely. The WSOD of death reared its head!
In this case, I couldn’t even access the admin panel, so I had to delete the plugin via FTP (more on this below). And voila! The site instantly came back online.
So a plugin we were testing took the site completely offline and had to be manually deleted from the server. These things happen more regularly than you may think, so that’s the whole point of this tutorial – so you’ll know:
- How to prepare for the WSOD.
- How to avoid it as much as possible.
- How to very quickly recover if it does happen to you.
Okay, so perhaps you’re asking…
Why Does the White Screen of Death (WSOD) Occur?
Well, the easiest way to describe it is – some code causes WordPress to crash to such an extent that the site goes offline entirely.
- Errors are when something goes slightly wrong, but the software continues to run.
- And exceptions are when something goes very wrong and the software crashes.
Catching exceptions means software crashes can be avoided. And well-written code should ideally catch exceptions and instead respond with a helpful message.
But to be frank – some WordPress plugins aren’t as well written as they ideally could be. Of course before a plugin is added to the WordPress plugin directory some basic checks are done, but that generally can’t predict whether it will clash with other plugins you have installed on your site.
As a further example of how plugins can cause issues:
I was working on another site, and this site was running WooCommerce and sold customized gifts for businesses. When I came on board they were customizing the gifts by simply asking the customer to fill in a form. This wasn’t an ideal approach at all since it added extra work.
The site owner wanted to add a lot of functionality, without going the custom coding route. This meant that as much as possible we had to find the solution from existing WordPress plugins. And with a bit of creative thinking, we managed to put this solution together.
That said, we had to test out a lot of plugins, and this process really made clear that some plugins are not well written, sadly. Some plugins contained bugs that negatively affected the functioning of other plugins. But in that particular project, none of the plugins produced the dreaded WSOD, however did cause odd behavior on the site.
Interesting Note: Odd behavior on a WordPress site can often be resolved the same way as I’m going to describe in this tutorial, since the WSOD is really just an extreme example of strange site behavior!
This all means that the more functionality you have installed on your WordPress site (and therefore the more complicated your site is), the more likely something will go wrong. Which is the nature of all software, really:
More features, means more complication, which means more bugs.
Now, jumping back to my membership site case study – exactly why this paid plugin took this client’s site offline is something that’s difficult to answer without doing quite a bit of testing (although I have my suspicions why). But clearly, this software wasn’t a good fit. For whatever reason, this plugin was having a very negative reaction to either:
- Existing active plugins on the site.
- The active theme on the site.
- A server-specific setting like available memory, or perhaps how the web host had configured things.
But recently, a WordPress update is helping you to solve the WSOD faster when it does occur. This was added in WordPress 5.2…
WordPress 5.2 and “Fatal Error Protection”
Rather than simply presenting you with an unhelpful white screen, when WordPress experiences an “exception” (crashes, basically), since version 5.2 WordPress attempts to:
- Present a helpful message.
- Email the administrator about the issue.
- Give the administrator an option to visit WordPress in “recovery mode”.
So with WordPress 5.2 and beyond, instead of the blank screen, you may instead see:
This doesn’t give you much information at all, but is more helpful (especially for your visitors) than an entirely blank screen.
And when you see this error, the administrator of the site will be sent an email similar to this one:
And so I click that link to enter “recovery mode” and I’m presented with this:
I follow the on-screen instructions which take me to the plugins screen:
So that gives me the opportunity to either fix the code issue directly – or – deactivate the plugin, bring the site back online, and then perhaps make the plugin active again by reverting to a previous version.
And so for fun, and for experimentation, here’s how I purposefully created the WSOD:
Experimenting With Generating the WSOD on Purpose
All I did was add a syntax error to one of the active plugin files. Basically – any PHP file that WordPress is actively using to run the site (plugin files, theme files, even core WordPress files) – introduce a deliberate error into it and watch your site go offline instantly!
I simply added an unnecessary space in the middle of the PHP function “defined”:
And by simply removing that space and updating the file on the server:
The site instantly comes back online!
So even a single small mistake in the code can crash your WordPress site. Therefore knowing how to quickly recover when your site does experience the WSOD is time well spent.
Section 2 – Prevention
Introduction – How to Avoid the WSOD
As shown in the examples above, it’s not really possible to avoid the WSOD entirely, since you don’t know it’s going to happen, until it does! Any new software added to a site, or even a WordPress update, has the potential to introduce issues.
Therefore it’s not so much about avoiding it, but it’s more about being prepared for when it does happen. This comes down to:
1) Knowing how to diagnose and fix WSOD issues quickly (this is what section 3 of this tutorial covers).
2) Working on your site in such a way that many of the most serious dangers are avoided entirely:
- If working on your live site – make changes to the site during a period when it’s less likely to affect visitors.
- Make sure you can quickly revert back to the previous version of the site, in case there’s an issue.
- And in general, especially if you’re making any major changes, it’s best to make those changes on a test (staging) site, and only once you’re happy with everything do you then move things over to the main site.
So let’s talk through each of these:
Make Changes (Especially Major Changes) During Quiet Periods
This approach is self-explanatory – if you’re working on your live site, and if there’s any risk at all of something going wrong (and there generally is such a risk), make the change during your quietest period of the week.
You wouldn’t make big experimental changes to a site just as you start a major product launch, of course! So when is your site the quietest? That’s probably the best time to make changes, since in case anything does go wrong it will affect the least amount of visitors.
Putting Your Site Into Maintenance Mode
Now, if you do choose to make changes directly to the live site – or – you’ve finished testing things on your staging site and are ready to move things over, you generally want to put the site into maintenance mode, so visitors see a message like this:
You can customize the message considerably more than that, and the simplest way to achieve that is through a plugin, which I’ll cover in a moment. Putting your site in maintenance mode really comes down to two approaches:
- The manual approach – quick and easy, but gives you a lot less flexibility.
- Using a plugin – slower, but gives you a lot more options.
Maintenance Mode – Manual Approach
This approach to putting your WordPress site into maintenance mode is very simple:
- Access your site via FTP (or through your web host’s file manager interface, if they offer one).
- Add a simple text file to the root of your website.
- And then simply delete the file when you’re ready to take the site out of maintenance mode.
Let’s walk through these steps…
Launch your FTP software, connect to your hosting, and navigate to the root folder of the site you’re working on:
Create a new file in that folder called .maintenance (note the . at the start).
In this example, I’m using FileZilla and you can create a new file by right-clicking:
And create an empty file called .maintenance:
You then edit the file to add code to it (or you could create the file on your computer and upload it, if you prefer to work like that):
And simply add the following code, then save:
Here’s the code, if you’d like to copy and paste it in:
<?php $upgrading = time(); ?>
And that’s it! Your site will be in maintenance mode – but, you won’t even be able to access the admin area. This is fine if you’re making changes via FTP however.
This is the most severe approach to putting your site into maintenance mode. So you may find using a plugin gives you much more flexibility:
Maintenance Mode – Some Plugin Options
It’s important to keep in mind that the following two states your site can be placed into are very similar:
- Maintenance mode.
- Coming Soon mode.
Both of them:
- Make your site inaccessible to regular visitors.
- While allowing you to work on the site.
The only real difference is the message you display to people who visit the site during this period.
So here’s three well-reviewed, widely-used, and regularly updated Coming Soon / Maintenance Mode plugins:
Maintenance Mode Plugin Walk-Through
Let’s do a quick walk-through of the Minimal Coming Soon & Maintenance Mode plugin.
Install and activate the plugin:
There’s quite a number of options available here, but let’s keep things simple for this demo:
And let’s see how that looks when you visit the site (without being logged in):
And this plugin still allows me to access the admin panel:
Next – if your site is important to you (and I assume it is!), you’ll want backups. So whether:
- Your site experiences the WSOD.
- Your site gets hacked.
- You want to move your site.
You’ll be able to very quickly recover.
Always Have a Backup of Your Site
In general, having a backup of your site is of course hugely important! But beyond just that, there’s things to keep in mind:
1) You should have more than one backup file.
- Let’s say you automatically back up your site every day, but each new backup overwrites yesterday’s backup. Well, on Saturday your site gets infected with malware and you don’t notice over the weekend. This would mean your one and only backup now also includes the malware, since it’s been more than 24 hours!
- So you need to back up regularly, but also have multiple versions of backups.
2) You need to regularly test your backups.
- Simply assuming your backups work may mean that one day, when you really need to restore your site, you come across issues you didn’t realize you had!
- Therefore – occasionally testing your backup files to make sure it’s all working okay, is something well worth doing.
And regarding options for making backups, as is so often the case in the WordPress world, it comes down to:
- Manual approaches
Let’s talk through the manual approach first, before we get to some plugin options. The manual approach is just two steps:
- Making a backup of your database.
- Making a backup of all your files.
Let’s go through these steps:
Backing Up Your Database Manually
Many web hosts offer the option through their control panel to immediately create a backup of a database. Plus, many web hosts include phpMyAdmin for managing MySQL databases (which WordPress typically runs on), so I’ll use that approach for creating a backup of a site.
So log into phpMyAdmin (ask your web host if you’re not sure how, but it’s generally through your web host’s control panel):
And from the list of databases on the left, click on the database you’d like to make a backup of, and then click on Export:
And that’s it. You can choose more advanced options if you’d like to, or simply stick with the “Quick” export method and press the Go button.
You’ll next be presented with a download dialog box for an SQL file:
And that’s it – you’ve saved a backup of your database!
Manually Backing Up Your WordPress Site Files
Use your favorite FTP software to access your site, select all the files in the root of your domain, and choose download. For example – I’m doing this in FileZilla:
But do be aware that downloading the thousands of files that make up a WordPress installation can take quite a while.
And that’s all you really need to do, to make a full manual backup of your site:
- Grab the database.
- And also all the files.
Now let’s talk through automating this process using plugins:
Some Proven Plugins For Easily Backing Up Your Site
Here’s a few highly reviewed, and widely used plugins for automatically backing up your WordPress site:
UpdraftPlus – Quick Plugin Walk-Through
Install and activate UpdraftPlus on your site:
Then navigate to the plugin settings page:
And you can create a backup manually on this page:
And click the Backup Now button:
Once your backup is complete it’s listed on the same screen:
And this gives you the option to download parts of your saved backups, if you choose:
And you can decide whether to restore everything, or just certain parts:
Once it’s gone through the process of restoring your site, you may see a message similar to this one:
But really, if you’re going to be making backup copies of your site, you want to automate the process and ideally store your backups somewhere else. Dropbox is a good choice, and this plugin gives you that flexibility:
So that’s one way to automate site back ups, to help you recover quickly from any site issues.
But importantly, and as detailed in the example at the start of this tutorial, if you experience the WSOD, you likely can’t even access the admin panel, so having access to FTP and the web host’s control panel is very important.
Ideally though, you would initially make any changes on a testing site, also often referred to as a staging site or staging area. This staging area could be on your computer, but ideally it will be at the same web host that your main site is hosted with.
Your Staging Area Options
Your staging area options are:
- Locally (on your computer).
- Remotely – but in a different hosting account to your main site.
- Remotely – in the same hosting account as the main site.
The best option is number three, and the main reason for this is you want to test things in a hosting environment that’s identical to your live site. Because different hosting accounts (and particularly when you’re running a local web server) can have very different configuration settings. And even slight configuration changes can make a big difference to how a site behaves.
That said, particularly when working locally, you can mess things up a lot more without worrying! So if you just want to get a feel for a plugin or a theme, working locally can be a great testing ground. However, if you want to accurately test how things will work before moving things across to your live site, then a staging area in the exact same hosting account will give you the best results.
But for the sake of completeness, let’s quickly talk through some options for setting up a local staging area:
Setting Up a Local Staging Area
For a local staging area, you’ll need to run a web server on your computer. There’s quite complicated ways to achieve this (using VirtualBox and Vagrant for example), and there’s also much simpler ways to achieve this. Let’s stick with the simple methods today!
Now – you may have heard of the LAMP stack. If you haven’t, it’s four pieces of software working together. Many web hosts run this combination of software on their servers, and the acronym LAMP stands for:
- Linux – The operating system.
- Apache – Web server software that handles site visitors and delivers pages/files.
- MySQL – Software that gives you database functionality.
- PHP – Having PHP installed allows your web server to understand and run PHP code (which is what WordPress is written in).
The reason I’m telling you this is that if you want a fully functional staging area on your local computer, you need:
- Operating system.
- Web server software.
- Database software.
- PHP installation.
Since you have a working computer I assume, that means you already have an operating system installed! But you likely don’t have the other three pieces of software. Luckily for you, there’s ready-made software that comes with all that bundled together. Popular free ones are:
For example, once you’ve installed XAMPP, you get a control panel that looks like this:
When you’re ready to run WordPress on your computer, launch Apache and MySQL by pressing the Start buttons:
And then open your browser and visit: localhost
You can then install and configure WordPress just as you would on a remote web server. However, rather than using FTP software to copy files, you simply use Windows Explorer (or the equivalent file manager on the computer you’re using).
And since you’ve also got a MySQL server, you can create databases through the phpMyAdmin interface:
And again as mentioned, a local staging area is great if you want to get very experimental, but since your local web server will very likely have quite different configuration settings to your web host, it’s best to test things out directly on your web host using a staging area.
Setting Up a Remote Staging Area
For setting up a remote staging area, you can either have a dedicated staging domain (This-Is-My-Testing-Domain.com for example – I’m assuming it’s not actually used by someone!), or simply use a sub domain. With a sub domain, if your main site is MySite.com, simply set up test.MySite.com, or whatever you choose.
And then make a copy of your main site onto the sub domain (you can use UpdraftPlus for this, as detailed above, or one of the other backup / migration approaches), and you can test there to your heart’s content. Whatever goes wrong, doesn’t matter! Simply set the site up again and continue testing.
As a side issue – if you have a staging site live online, there’s a low chance that someone might stumble across the test site, or even perhaps that the site will end up in Google’s index. Unlikely, but perhaps slightly possible, and not something you want.
To get around this issue, you could install a maintenance mode plugin, also as detailed above, or an approach I like to take is the following:
Limiting Remote Staging Area Visitors by IP Address
I use a domain ForDemos.com… funnily enough, for demos! Try to visit it if you like, and you’ll see the following message:
You won’t be able to access the site at all. The reason for this is I’ve configured it so only my IP address gets access to the site.
Now, there are plugins such as this one, that allow you to achieve this:
But for a site I’m doing a lot of tests on, I don’t want anyone except me to even get through to WordPress. In other words, I want to block traffic at the web server level, rather than at the WordPress level.
You can achieve this using htaccess, and this assumes you’re running the Apache web server. If your web host isn’t running Apache, then you’ll need to see how to do this for your particular web host, or you’ll need to use a WordPress plugin like the one linked above.
So FTP into the root of your staging area domain, and see if a .htaccess file exists:
Important – .htaccess (note the . at the start) is a hidden file. So make sure the FTP software you’re using is configured to show hidden files:
If it still isn’t showing, try the following – in your WordPress control panel, visit Settings / Permalinks:
And without changing any settings, simply press Save Changes on that screen:
Then check if a .htaccess file has appeared.
Alternatively, if you know you’re running on Apache, you can simply create a new file via FTP:
Note that your .htaccess file is simply a text file, and it will either be blank (if you’ve just created it via FTP), or contain some code specific to WordPress, like this highlighted section:
The section below that is what you want to add – either below the existing WordPress code, or simply add it to the top of the file if your htaccess file is blank:
Here’s the code you can copy and paste:
Order Deny,Allow Deny from all Allow from 188.8.131.52
Of course, change the 184.108.40.206 IP address to your IP address. Find it via Google:
Once you’ve made these changes to the htaccess file and it’s in the root folder of your staging site, only you with that IP address will be able to access the site at all.
Want to double-check? Simply change one of the numbers in the file, re-upload it, and see if you can access the site.
If you can’t – congrats! You’ve set it all up correctly.
If you can access it – go through these steps again, just to make sure you haven’t missed anything.
And if your IP address changes occasionally (rebooting your router may change your IP address, for example), then simply find your IP address again, update it in htaccess, and you’ll have access again.
By working on a test site in this way, you can do pretty much whatever you like. No one else has access, and if something goes wrong, you just recreate the site and continue testing.
Replacing Your Live Site With Your Staging Site
To replace your live site with your staging site, you simply need to move everything over. Either take the manual approach (copy files and database), or the plugin approach.
Of course, make a right-up-to-date backup of your live site before you make this change. And as detailed above, choose a quiet period if possible and go into maintenance mode, just in case something goes wrong.
Then you can replace the live site with the staging site, and while it’s still in maintenance mode (if you’re using a plugin for that), give it a quick test to make sure it’s behaving as it should be. If yes, take it out of maintenance mode.
Next you quickly start testing the site as a visitor (in a different browser, in incognito mode, on your phone…) and make sure things are looking okay across the board.
All okay? Great! You may want to keep testing, but it looks like the new version of the live site is okay.
How Your Web Host Affects Things
It’s important to mention that your web hosting set up can have a big impact on how your site runs. If I can return to the example at the start of this tutorial about the plugin that took the client’s website entirely offline, I have a very strong suspicion that it was due to the web hosting set up.
This client was on a very low end shared hosting plan. And this hosting plan struggled to even keep up with a pretty simple WordPress installation. So as soon as a plugin was installed that tested the limits of this hosting plan, the site went offline.
I tested another plugin with this hosting account, and while that particular plugin didn’t take the site offline, it stopped another plugin (Visual Composer – a page builder) from working as it should. This hosting plan was so limiting, it introduced serious issues where there shouldn’t be any.
For example, in the hosting account control panel it was showing CPU (processor) usage at 99% or 100%, pretty much constantly. This should never be the case!
So clearly this web hosting account was right at its limit. So do be aware that while you can change configuration settings (as I’ll cover shortly), your hosting plan has physical limitations on how much usage it can support. And very basic plans can really limit what your site can do, can slow things down, and even take your site offline.
Bottom line – if your site is important to you, get decent hosting. And it needn’t be expensive at all, but the right choice here can make a huge difference to your site.
Section 3 – Fixing the White Screen of Death
The simplest way to fix this is to ask yourself:
“What did I do, just before the WSOD occurred?”
Because if you made a change to the site, and suddenly you’re presented with a blank screen, that’s a big clue that the action you just took is directly responsible. This reason alone is why it can be incredibly helpful to only make one change to your site at a time.
I know it’s slightly more time-consuming to update each plugin individually, but if let’s say you update five plugins at once and suddenly the WSOD appears, you don’t know what caused the issue, since immediately you have five possible suspects, rather than just one.
Cautious and methodical wins the day. Rushing through things, or making changes to a site when you’re tired at the end of a long day, can often mean things go very wrong, very quickly.
Quick Fix Options
Solving this issue quickly often comes down to:
- Disabling all plugins to see if that fixes things, and if it does then narrowing the issue down to a specific plugin (or specific combination of plugins).
- If that doesn’t fix things, try reverting back to the default theme.
- And if things still aren’t working, reinstalling the WordPress core files may help.
In many cases this approach fixes the issue, brings the site back online, and gives you the time to research the plugin or theme issue in more depth.
A couple of points to keep in mind:
Determine When and How it’s Happening
You’ll want to become clear exactly where the issue occurs – and this may involve testing across multiple browsers / devices:
- The admin panel?
- For logged in users?
- For non logged-in visitors?
- For absolutely everyone?
Do this test quickly just to start to narrow down the issue a little. You may find this somewhat helpful for resolving the issue.
Refreshing Your Cache
As you work on fixing this issue, do make sure you’re not looking at an out of date version of your site. In particular:
- Disable any caching plugins (if you can’t access the admin panel to do this, rename the caching plugin folder – see below).
- Make sure to do a hard refresh so you’re not seeing a cached version. Check how to do this on your computer. On Windows it’s typically CTRL + F5, for example.
Now let’s start fixing the issue…
Can you access the WordPress admin panel?
If yes, you can disable plugins through the admin interface.
If not, you’ll need to disable plugins via FTP or through your web host’s file manager interface. To do this, you navigate to the following folder for your site:
Here’s the folder in FileZilla:
A quick way to see if one (or more) plugins is causing the issue, is to disable all plugins. You can achieve this by renaming the plugins folder. I often simply add the ~ (tilde) character at the start:
By changing the name of the folder, you immediately disable all plugins. So test if the site comes back online. If yes, you’ll know it’s one or more plugins causing the issue.
To find out exactly which plugin is causing the issue, rename one plugin folder at a time:
Going through each plugin folder in turn – rename the folder, and see if the site comes back online. If yes, that’s the plugin causing the issue. If no, revert the plugin folder name (so you’re only testing one plugin at a time), and move onto the next plugin folder.
Taking this approach should narrow the issue down to one plugin. However, if:
- You know for sure that it’s plugins causing the issue (because disabling all plugins brought the site back online).
- Yet disabling and re-enabling each plugin in turn doesn’t solve the issue.
That would mean it’s a combination of plugins causing the issue. It then becomes a matter of trying different combinations, to narrow the issue down to two or more plugins that aren’t working well together.
Since testing plugin combinations can be long-winded and time-consuming, reverting to a site backup may be a lot faster.
Alternatively – once you know exactly which plugins are causing the issue, and you have those plugins disabled, you’ll see that the site comes back online but perhaps a lot less functional than you would like it to be. So if a plugin update caused this issue, perhaps reverting to the previous version of the plugin may solve the issue. This would allow you to keep the plugin activated – without – taking the site offline.
To get the previous version of a plugin, if it’s a paid plugin you may need to contact the plugin developer. Whereas if it’s a free plugin from the WordPress directory, generally a few previous versions are available. You can download them manually by visiting the plugin page at WordPress.org and clicking on Advanced View:
And at the bottom of that screen, you’ll be able to download previous versions (within limits, since not every single previous version will be available):
Alternatively, you can install the following plugin that allows you to easily revert to a previous version:
So if you’d like to keep all your existing functionality while also keeping the site online, your options are:
- Revert to the previous version of a plugin.
- Revert to a previous backup of the site.
- Contact the plugin creator about the issue.
- Find a way of including that functionality either with a different plugin, or through custom coding.
But if your issue isn’t plugin related, then let’s try out reverting to the default theme…
There’s a small chance your site is running on the default WordPress theme, but I would say it’s pretty unlikely since changing the theme is one of the first things people do with any new WordPress site!
And as I write this, the default theme is Twenty Nineteen. So if your site isn’t running on that – and – if disabling plugins doesn’t solve the WSOD issue, it’s time to test reverting to the default theme.
Important note – I’ll talk through this in more detail in Section 4, but even if the theme is causing issues, disabling the theme may not resolve the WSOD. It didn’t in my case even though the theme files were introducing significant issues. This means disabling the theme is worthwhile as a quick test, but the results may still be misleading. It’s not as clear at all as when you disable plugins.
For disabling a theme, the exact same approach is used as for disabling plugins via FTP – rename the folder of the theme you’re using, and your site reverts back to the default theme.
My demo site is currently using the Twenty Sixteen theme:
I can go into the themes folder and deactivate one theme at a time by renaming the folders:
The same options present themselves:
- Revert to a previous version of the site.
- Revert to a previous version of the theme (if available).
- Contact the theme developer about the issue.
- Use a different theme on the site.
But if you find that the WSOD is neither plugin nor theme related, it’s time to try reinstalling the core WordPress files. Let’s do that now.
Now when I say “Reinstall WordPress”, what I really mean is simply re-uploading the core files. You can reinstall the core WordPress files two ways:
- Through the admin panel (if you have access).
- Through FTP.
If you have access to your admin panel, visit the Updates screen and simply update or reinstall WordPress (depending on whether you’re on the latest version or not):
Or reinstall WordPress core files by FTP. Either download the latest version, or download the same version of WordPress that your site was running before it crashed (this may be safest, if you know exactly which previous version your site was on):
Next unzip all the files:
And upload them by FTP, overwriting the existing files.
In your FTP software (I’m using FileZilla in this example), navigate to the folder on your computer where the WordPress files are, select all the files, and upload them to the correct folder on your server.
Here’s the folder on my PC, in the left pane of FileZilla:
Note: You likely want to deselect wp-config-sample.php as that isn’t needed.
And make sure you’re uploading to the root of your existing WordPress installation, so the existing files get overwritten. Here’s my right pane (remote server) in FileZilla:
Question: Have you changed any of the WordPress core files? You really shouldn’t have. But if you have, any time WordPress updates (or in this case, you overwrite the existing files manually), you’ll of course lose any changes to core files you’ve made.
So upload, overwrite the existing files, and this will help to ensure that there’s no missing or corrupted core WordPress files.
Now try accessing the site.
If yes – great! Log in as administrator, and check it all works.
Note: There’s a small chance you’ll see a message about your database requiring an update. If this is the case, proceed with the database upgrade which only takes a few seconds at most.
But if you’re still experiencing site issues, let’s go further in depth into what may be causing the issue, and potential solutions.
Not Fixed? More In Depth Options…
By following the steps above, if you discover that the WSOD is not due to:
- Core WordPress files
Then it’s time to look at other possible sources of the issue.
Enabling WordPress Debugging
Enabling debugging in WordPress means that any error messages are (by default) displayed on the screen. You generally want this turned off since:
- Error messages displaying when people visit your site can look very unprofessional (and may also confuse them).
- Error messages can often display details specific to your website set up, which could make it easier for someone to hack your site.
That said, if your site is experiencing the WSOD, having debugging enabled can give you a lot of helpful information about what could be causing the issue. For example, at the start of this tutorial I purposefully generated the WSOD on my demo site. I’m going to do that again, but this time with debugging enabled. This will allow us to immediately see where the issue is coming from.
To enable debugging in WordPress, open up the wp-config.php file in a text editor:
The main setting you want to pay attention to is WP_DEBUG:
Simply change the value to true:
There’s other debugging settings also available, but you generally don’t need to change those. But for the sake of completeness, let’s quickly touch upon them.
You can have error messages stored in a text file (a log) by including the following line in wp-config.php (or changing its value if the line already exists):
define( 'WP_DEBUG_LOG', true );
By default, those error messages are stored here:
Or you can specify a different location this way:
define( 'WP_DEBUG_LOG', 'wp-includes/error-log.txt' );
This particular example URL would save error messages to the error-log.txt file in the wp-includes folder. Or you can choose any other relevant address on your server.
Now, the following value is set by default to true, even if it isn’t included in wp-config.php: WP_DEBUG_DISPLAY
When this value is set to true, and when debugging is enabled, errors appear on the screen. And when you set this value to false, it means errors aren’t sent the screen. This means of course that if it’s set to false, you need WP_DEBUG_LOG to be set to true, otherwise you won’t see the error messages anywhere!
For example, the following lines of code in the wp-config.php file will output error messages to a log file in your WordPress root directory, and not to the screen:
Now let’s take a look at the next possible source of issues.
Memory Limit Issues
Lack of available memory can cause issues with WordPress. That’s what I believe happened in the case study at the start of this tutorial. The new plugin required more memory to run than was available, so the site went offline entirely.
Just like your computer has a certain amount of memory available, so too does your web hosting, which limits what your site can achieve, and how well it runs.
If your site is important to you, and you want things to work well (I assume you do!), investing in either a VPS, or WordPress specific hosting, can be money very well spent. And it needn’t really cost much at all. Going too cheap with your hosting is false economy, since you can be introducing significant technical limitations on your website.
And within the limits of your web hosting, there’s also settings you can apply assigning memory to your site. First of all, here’s a quick way to check how much memory your site has access to right now:
My demo site needs work since it’s only at 48% site health. But since this site is just for demonstrations, optimizing it isn’t high on my to-do list! Hopefully the number you see for your site will be quite a bit higher, however.
Click on the Info link, and you’ll see a screen like this one:
And here you’ll see helpful information about your web hosting, including how much memory is available to PHP:
The PHP Memory Limit value is the maximum amount of memory available to each visitor to your site. The WordPress default value here is 40MB, and I would say in most instances (unless your site is doing something particularly complicated) that should be enough.
But in case you need to change this setting, I’ll list a few ways to do that. There’s a couple of important points regarding this however:
1) The change may not take effect immediately.
2) To help apply the change, you may need to:
- Kill all running PHP processes.
- Restart / reboot your web hosting.
Killing all PHP processes simply means all PHP running in memory is cleared, so that everything to do with PHP (and therefore WordPress) starts with a blank slate.
You may be able to kill PHP processes through your web host’s control panel, or ask your web host’s support to do it for you. You may also be able to achieve this via SSH, but talking you through how to kill PHP processes through the command line is beyond the scope of this tutorial. That said, your web host may well have tutorials on how to achieve this, so do check their knowledge base.
And you also may be able to restart your web hosting through the control panel provided to you. Otherwise you might need to ask your web host if they can do it for you. Restarting / rebooting your web hosting would also have the effect of killing all active PHP processes of course, since it works like rebooting your computer where everything starts over fresh.
So as I talk through the different places you can apply this memory setting change, you may find the following approach helpful:
- Make the change.
- Visit your site and see if the change has gone through.
- If not – kill PHP process, or preferably reboot.
- Check again.
- If the change hasn’t been applied, try changing the setting in the next location as detailed below.
It’s very important to mention that we’re now getting into an area that is heavily affected by your web host. Some web hosts don’t let you change these settings at all, while other web hosts will allow you to make such changes but only in a limited way. In other words, changing PHP settings can be a bit of an inexact science as it very much depends on your web host and what they allow you to change.
With that in mind, let’s start with the first approach.
Increasing Memory Through wp-config.php
This approach involves simply adding a line of code in your wp-config.php file, which is in the root directory of your WordPress installation. Of course check the line doesn’t exist in this file before adding it, just so it doesn’t end up in the file twice.
And note that any code changes to wp-config.php must be made before the following line (your line numbering will likely be different to mine, but that’s the specific code to look out for, and it’s very near the end of the file):
And there’s two settings to keep in mind here, although one is used a lot more than the other:
define( 'WP_MEMORY_LIMIT', '64M' );
This line of course would assign up to 64 megabytes of memory each time WordPress runs. For example:
- 1 visitor = 1 running instance, so that instance has up to 64 megabytes available, but doesn’t need to use all of it, it may just use a portion.
- So 10 visitors = 10 WordPress instances, each with up to 64 megabytes available. Therefore the absolute maximum they would use together would be 640 megabytes.
You can increase this number further if your site needs it, but at a certain point you will hit the physical limits of your web hosting plan (how much physical memory you actually have access to).
Once you’ve added this line and have rebooted (ideally) or alternatively killed PHP processes, visit your admin area if you can access it, and navigate to the Site Health screen, and click on the Info link at the top. Here again WordPress will show you how much memory it has access to. Has it increased? If yes, great! The new setting has gone live. If not, read on.
The second memory setting that’s worth mentioning (but which is used considerably less) is the following:
define( 'WP_MAX_MEMORY_LIMIT', '128M' );
Again, set it to whatever value you choose. Be aware that this memory setting only applies to people logged in as administrator, and doesn’t affect regular visitors to your site.
And once again check if the available memory value has changed or not. If it hasn’t, you can remove the lines you added in wp-config.php, and instead attempt to make the change through the htaccess file (assuming your website runs on Apache).
Increasing Memory Through htaccess
You can also attempt to change the PHP memory limit setting through the .htaccess file which may already exist in the root of your WordPress installation. This assumes your site is running on the Apache web server software.
Here’s an example of the line of code you would add to the file:
php_value memory_limit 128M
(Or whichever value you choose.)
As detailed earlier in this tutorial:
- The .htaccess file is found in the root of your WordPress installation.
- To find it via FTP, it’s required that your FTP software is showing hidden files.
- And if it doesn’t yet exist, you can create a new blank .htaccess file through your FTP software (remember the period at the start), or simply press Save on the Settings / Permalinks screen in the WordPress admin panel.
If changing the memory limit value in wp-config.php hasn’t made a difference, try changing it here and see if that helps things. Again, remembering to reboot / kill processes if possible, just to ensure WordPress is looking at things fresh.
But if that doesn’t help, here’s a further approach you can take:
Increasing Memory Through PHP.INI
Many web hosts don’t allow you to change php.ini settings directly, or if they do, typically the changes you can make are rather limited. And again, if you’re unsure at all, ask your web host about this.
And if you’re not familiar with it, the file php.ini contains all PHP configuration settings. And the line of code you’re looking to change in that file is:
memory_limit = 128M
Of course, your php.ini file may have a different value.
If you’re able to make unrestricted changes to php.ini, you can change the value there directly. And again, changing settings this way may well require a reboot of your VPS (or whichever type of hosting you have).
File and Folder Permissions
If you’ve got to this stage in the tutorial and things still aren’t working, there’s potentially a chance you’re experiencing issues because of file / folder permissions. Frankly, it’s quite unlikely I would say, but it doesn’t hurt to quickly check this if your site is still offline.
You can set permissions for different files and folders on your server. Permissions are set for three groups of people:
And permission types break down into:
And combinations of settings have different numeric values, and you can set these directly through your FTP software. For example, here’s the permission setting for the WordPress index.php file in the root of my domain:
In many instances for WordPress the following settings will work well and also help keep things secure:
- Files are set to 644.
- Folders are set to 755.
And you can use FTP software to apply these permission settings to all files or folders in your website at once.
In FileZilla, select all files and folders in your website root folder, and right-click:
Choose to apply 755 across all folders and sub-folders:
Once that has completed, run it again but this time applying 644 to all files:
And there’s a couple of further small changes. These settings are in fact the recommended permission settings according to the WP Security plugin:
So the further permission settings are:
- Root folder (which of course contains all WordPress files and folders) is set to 755.
- The wp-config.php file is set to 640.
Once these permissions have applied, does that help you regain access to the site? If not, if nothing else these settings are good to apply to your site from a security standpoint.
Now let’s talk through a further recent case study of mine. Moving a site generated the WSOD, and in this instance no single approach solved the issue, but rather a combination of approaches was needed.
Section 4 – In Depth WSOD Case Study
I thought this case study would be worth including too, since it demonstrates:
- That unexpected, even somewhat illogical site behavior may be part of a WSOD (so a little detective work is often needed).
- That the solution isn’t always as tidy as you’d like it to be.
- That having debugging turned on is incredibly helpful for short-cutting the process.
Recently I moved a site from one web host to another. Often, moving sites is quite straightforward, however that wasn’t the case this time for a number of reasons which I’ll detail. And a number of important points this move made abundantly clear were:
1) It’s well worth trying to replicate the existing (current web host) configuration settings at the new web host, to make it as similar as possible. Otherwise complications can be immediately introduced, as you’ll see.
2) It can be helpful to get WordPress, themes, and plugins right up to date at the existing web host, before making the move.
3) Try to move the site when you’re not in a rush, so you can test things fully before changing DNS settings. And there’s two ways to test at the new location, before you’ve changed DNS settings:
- Use another domain (or sub domain) at the new web host for testing, and then when you’re ready to change name servers, you can map your main domain on top of the testing domain. This is known as parking a domain on top of another. Basically, you have two domains pointing to exactly the same location on your web server.
- Or you can change your hosts file so that you’re looking at the new web host when accessing the domain, while everyone else on the internet is still going to the previous web host. It’s beyond the scope of this tutorial to detail editing your hosts file as it does depend on which operating system you’re running, but it’s fairly straightforward to apply.
So just as I’ve done in the past when moving sites:
- I downloaded all the files from the existing host via FTP.
- I exported a copy of the database.
- I uploaded the files to the new host.
- I created a new blank database at the new web host.
- I imported the database file into the new blank database.
And often that’s largely all that’s needed (along with a couple of other tweaks). And since this site wasn’t really receiving traffic, downtime wasn’t an issue so I went ahead and changed name servers.
Well, once the change started to go through, I was presented with the wonderful WSOD, and:
- Disabling plugins had no effect.
- Disabling the theme had no effect.
- Reinstalling WordPress didn’t help.
So it was time to start diagnosing the issue further. I enabled WordPress debugging, and it became clear that part of the issue was “too many redirects”.
This was because the new web host was automatically changing domain.com to www.domain.com. But, in WordPress the site setting was domain.com. In other words, the web host and WordPress were in a constant battle to keep / remove the www part of the address. And this resulted in the site redirecting from www to no-www, then back to www… and it all contributed to the site going offline.
So I disabled that automatic redirect in the web host’s control panel, and that was a step in the right direction. Four lines of debugging errors became two, which was certainly positive.
But to complicate things further, the old hosting had SSL as part of the address (https://) whereas the new hosting did not. So that was another issue to resolve since SSL was not working at the new web host, yet. Again, since downtime wasn’t an issue, I changed DNS before creating a certificate at the new web host. Whereas if minimizing downtime is important to you (and in most cases that’s very important), you would set up SSL at the new host before changing name servers.
But for now, to access the site using standard http:// (no SSL), I accessed the database using phpMyAdmin and in the wp_options table made changes to these two options:
The siteurl and home options were manually changed from https:// to http://. This helped me get a little more access to the site.
And it also became clear from the debugging messages, that the site theme was introducing many issues. Exactly why it worked at the old host but not at the new host was a bit of a mystery, but it seems all these issues together were taking the site offline. This meant it really was a combination of factors all working to cause significant problems at the new web host.
I updated the site theme to the latest version, but, starting fresh rather than overwriting the existing files. For whatever reason with this particular theme, overwriting old theme files with new theme files doesn’t work and instead introduces a range of problems. So instead, I renamed the existing theme folder (just to keep it around, but unused), created a new empty folder with the theme name, and uploaded the latest theme files into that folder. And that solved the last of the problems and I finally had full access again.
Next I logged into WordPress and was presented with an “Upgrade Database” message. I went ahead with that, and once it was complete, everything was looking good. The last step was to create a Let’s Encrypt certificate for the site, change the site back to using SSL, and give everything a quick test to make sure things were running smoothly.
So once again, it’s well worth keeping in mind when moving a site:
- Update the site fully before the move – plugins, themes, and WordPress (one at a time though, just so you’re able to recognize and fix any issues this may introduce).
- Set up SSL at the new location before the move if possible.
- Make sure the URL matches exactly (including no automatic redirects).
- Pay attention to anything else that’s different, including PHP versions, MySQL versions, and so on. Differences might be unavoidable, but do review this and keep this in mind if possible.
- Test fully at the new location using a temporary domain, or by changing your hosts file, before changing name servers.
Section 5 – Wrapping Up
My goal with this tutorial is to offer you one of the most in depth resources for helping solve the white screen of death issue in WordPress. Hopefully I’ve come somewhat close to that goal! And also it’s been my intention to present this in a way that’s:
- Easy to follow along with and apply.
- Yet also in depth.
And even though I would say the approaches I’ve detailed here will be helpful in most cases, as you can see from the case study in Section 4, sometimes resolving the WSOD can require some care, methodical thinking, and a combination of solutions. And ideally now, what you have through this tutorial is a toolbox of approaches that can help you avoid (where possible) and fix (where necessary) the WSOD when it presents itself.
And in particular with the features included in WordPress 5.2 and beyond, and with debugging enabled, you should generally be able to understand and resolve the issue rapidly.