Troubleshooting the WordPress White Screen of Death

Introduction

WordPress is a popular open-source web publishing platform. It's written in PHP and uses a MySQL database to store dynamic content. PHP issues with themes or plugins can cause the WordPress site to display nothing but a white screen, known as the White Screen of Death. The error also prevents access to the administrative dashboard. This troubleshooting guide will help restore access to your WordPress site.

First Steps

Before performing any of the steps below, check the server console at https://my.vultr.com. If there are any "out of memory" errors on the screen, reboot the instance. This step will often temporarily correct the problem. If the problem recurs, you may need to upgrade your server with more memory or disk space.

Take a Snapshot

Before performing any troubleshooting, it is vital to have a reliable backup as a starting point. Please do not skip this step. Vultr snapshots allow you to restore an exact point in time backup in case something goes wrong. Navigate to https://my.vultr.com/snapshots/ to make your snapshot. See our Snapshot Quickstart guide for more details.

Turn on Debugging

Often, depending on the cause of the error, WordPress will show debugging information when requested. Enable WordPress debugging with the WP_DEBUG directive in wp-config.php.

1. Edit wp-config.php.

    # nano /var/www/html/wp-config.php

2. Look for this line. Change the WP_DEBUG flag to true as shown. Add the line near the top of the file if it does not exist.

    define( 'WP_DEBUG', true );

3. Reload the site in your browser. Inspect the error message for clues about the source for the error.

Increase the PHP memory limit

By default, WordPress allocates a maximum of 40MB of memory for the website and 128MB for the administrative dashboard. Sites with many plugins and complex themes may run out of memory with these limits. Increase the memory limit to diagnose this issue.

1. Edit wp-config.php.

    # nano /var/www/html/wp-config.php

2. Insert these two directives just above the line that says "That's all, stop editing! Happy blogging". You will find that line near the end of the file.

    define('WP_MEMORY_LIMIT', '512M');
    define('WP_MAX_MEMORY_LIMIT', '512M');
    /* That's all, stop editing! Happy blogging. */     

WP_MAX_MEMORY_LIMIT is the maximum about of memory PHP can use in the administrative dashboard. WP_MEMORY_LIMIT is the memory allowed by WordPress for the public-facing site. This example allocates 512 MB for both. Use appropriate values. Don't define more memory than your server has available.

Themes

If you have updated or changed your theme before seeing the white screen on your site, disable the theme.

1. SSH to the Vultr instance as root.

2. Rename the theme folder to disable the theme.

    # cd /var/www/html/wp-content/themes/
    # mv exampletheme exampletheme_disabled

3. WordPress will display an error to public users because it can not find the theme.

4. Navigate to https://example.com/wp-admin/.

5. Go to the Appearance / Themes page. A message appears at the top of the page:

    The active theme is broken. Reverting to the default theme.

You may need to manually install and activate a new theme to continue diagnosing the site.

Disable all Themes

As a last resort, you can rename the entire themes folder to themes_disabled.

# cd /var/www/html/wp-content/
# mv themes themes_disabled

Create a new, empty theme folder. Give ownership to www-data.

# mkdir themes
# chown www-data:www-data themes

The wp-content folder should now look like this:

# ls -l
total 24
-rw-r--r-- 1 www-data www-data   28 Jan  8  2012 index.php
drwxr-xr-x 4 www-data www-data 4096 May  5 19:36 plugins
drwxr-xr-x 2 www-data www-data 4096 May  5 19:47 themes
drwxr-xr-x 6 www-data www-data 4096 May  5 19:37 themes_disabled
drwxr-xr-x 3 www-data www-data 4096 May  5 19:47 upgrade
drwxr-xr-x 3 www-data www-data 4096 May  5 19:37 uploads

The public site will display an error, but the administrative dashboard will be available.

Navigate to https://example.com/wp-admin/, then install and activate a new theme under Appearance / Themes.

Plugins

If you know the plugin you modified before WordPress white screened, then you can rename that plugin directory. In this example, the theme folder badplugin is renamed to badplugin_disabled.

# cd /var/www/html/wp-content/plugins/
# mv badplugin badplugin_disabled

The easiest way to locate a troublesome plugin when many plugins were updated is to disable them all, then turn them back on one at a time.

1. SSH to the Vultr instance as root and rename the plugins folder. This will allow you to access the Admin panel.

    # cd /var/www/html/wp-content/
    # mv plugins plugins_disabled

2. Navigate to your Admin panel, then go to Plugins / Installed Plugins. WordPress will query the folder, find no plugins, and disable them all in the database.

3. SSH to the Vultr instance as root and rename the plugins_disabled folder back to plugins.

    # cd /var/www/html/wp-content/
    # mv plugins_disabled plugins

4. Navigate to your Admin panel, then go to Plugins / Installed Plugins. You will see that all the plugins are now disabled, and the site should have basic functionality.

5. Enable one plugin.

6. Go to the home page, and use F5 to force the browser to reload the page and skip the cache.

7. If the site loads without the white screen, repeat steps 4, 5, and 6, enabling one plugin at a time until you locate the plugin that causes the White Screen of Death.

8. SSH to the Vultr instance as root and rename troublesome plugin folder.

    # cd /var/www/html/wp-content/plugins
    # mv badplugin badplugin_disabled

Conclusion

These diagnostic steps will resolve many WordPress issues.

Frequent, automatic backups for WordPress are the best policy. It's often much faster to roll back to a recent backup when your site experiences issues. Vultr's automatic backups create snapshots for easy recovery of the entire server. We also recommend WordPress backup plugins for off-site database and file backups.