How to deal with a white screen after migrating

If, after migrating (cloning) your website to a new location, you get a blank screen on the website front-end (i.e. when visiting the website’s “home page”), then this article is for you.

The white screen means that WordPress (or to speak more accurately, the PHP engine that WordPress runs on) crashed. So, the question is: why did it crash? What component is causing it to crash?

Migration completed?

Firstly, did the migration operation appear to actually complete? i.e., in the browser window that is showing its progress, does it show it as having finished? If it appears to still be running, then you should let it complete. If it appears to have simply stopped, then it is likely that your webserver is set up with overly-low time limits. The best thing to do is raise that limit (speak to whoever runs your webserver about this). Or, you might be able to work around this by migrating piece-by-piece (i.e. don’t do all the parts at once – e.g. do the plugins/themes/others, and then do the uploads in the next step, and then do the database last). In the rest of this article, it is assumed that your migration is shown as having completed.

Usual causes

Since you had WordPress running before, the most likely cause is a plugin or the active theme in the backup set which you have just imported. Sometimes, plugin (or theme) authors have only tested their plugins (themes) on a restricted range of WordPress setups. Or, the plugin might simply be much older than the version of WordPress you are now running, and never have been tested on current versions (e.g. an obsolete,  no-longer-maintained plugin). There are several ways this can happen. e.g. The plugin has only ever been tested on Linux and never on Windows – and has some faulty code which wrongly assumes that everything works like on Linux. Or the plugin has only been tested on PHP 5.2, which is what your original site is using… but your new cloned site is using PHP 5.4 (or the other way round).

Turn on debugging messages

Sometimes, you can find the culprit very quickly, by turning on debugging messages. Edit the wp-config.php file in your WordPress installation (this file is usually in the root directory of your website), and change the setting for WP_DEBUG in that file from false to true. Then try to load your site again. It may now show you an error message which allows you to spot which plugin is the cause.

Read your PHP error log

If that does not show you the cause, then you should try to find where your PHP error logs are. If someone else is running the webserver, then ask them where to find them. Look for the most recent error messages (try to load the site again if it’s been a long time).

Increase the PHP memory limit

On some webserver setups, WordPress crashes due to hitting the configured memory limit, without showing the error message. Add this to your wp-config.php file, and then try to load your site again:

define('WP_MEMORY_LIMIT', '512M');

Find the culprit

If this still does not help, then the remaining method is to disable your plugins and theme. You could do this one-by-one, or several at a time if you have lots. To do this, you need to rename their directories. At this point, you probably will not be able to log in to your WordPress dashboard – though it is worth a try. (i.e. Visit the /wp-admin page on your site). If you can, then you can disable plugins on the “Plugins” dashboard page – and then try visiting the site front-end – keep doing this, until you find the culprit.

If you cannot log in to the dashboard, then you will have to disable your plugins/theme by renaming the folders by hand. These are found in the folders wp-content/plugins and wp-content/themes in your WordPress install. An individual plugin (e.g. the “Akismet” plugin) will have a related name (e.g. wp-content/plugins/akismet). You can then rename it to anything else – and this will disable it (e.g. rename wp-content/plugins/akismet to wp-content/plugins/akismet2). This will not make the site front-end start working – if a plugin is missing, then this will actually make sure that the front-end does not work. However, the point is that, when the plugin that stops you from being able to log in on your dashboard has been renamed, you will then be able to log in to the dashboard. This will then show you which plugin (or theme) was the cause. You will then want to rename all the “innocent” plugins back to their original names, and use the “Plugins” page on the dashboard to re-enable them.