HUB - White Screen After Installing the Theme

If you upload the theme and activate it, and see nothing but a white screen, please read the following information. This is more common than you might think, and it can be frustrating to sort out. First, it is important to understand what the white screen, often referred to as the "white screen of death," actually means. Simply put, there is an error that you can't see. The reason you can't see it is because WordPress is not displaying the error that is causing the problem. When attempting to diagnose a white screen condition consider what you did before the condition occurred:

  • Did you install an upgraded version of WordPress, and did you check to see if the white screen occurred before you installed and activated your theme?
  • Did you install any plugins prior to installing the theme?

There are several causes of this condition. We will be addressing the ones most likely to occur -- Plugins, Theme, and Other Causes.

Plugins

No matter how hard developers try, it is basically impossible to write plugins that will work and play well together with every single theme. The same is true in reverse. If you experience a white screen after activating the theme, the problem could be a plugin that is in conflict with the theme. Try the following:

  • If you can access the admin area of your site, but get the white screen on the front end, login to your admin section and deactivate all plugins. After doing so, check your front end page again. If you can see it, you have a plugin conflict. Now, start activating each plugin one by one. When you see the white screen again on the front end pages, you will know that the last plugin you activated is the likely culprit. Deactivate it and continue checking all remaining plugins one by one to make sure there are no others.
  • If you are getting the white screen on the front end and the back end admin area, then you will need to access your site via an FTP client. A little known trick is to change the name of your  /wp-content/plugins folder to something else temporarily like "plugins.bak." This will make WordPress ignore your plugins. Then check to see if this resolves the problem. If it does, log into your admin section and then change your plugin.bak folder back to plugins. Then deactivate all of your plugins via your admin page.

Themes

The most likely issue associated with a theme being the cause of a white screen condition is when the upload of the theme did not complete the transfer of all files, the transfer resulted in corrupted theme files, or you have PHP configuration memory limits set too low. Try this:

  • If you can access your admin area, disable all plugins as described above, change the theme to one of the WordPress default themes. Check to see if this resolves the problem. If it does, try reinstalling the theme by completely removing the old copy in /wp-content/themes/ and installing a fresh copy. I recommend using FTP to do this because of you less likely to run into errors than when you use HTTP WordPress theme installer. Activate the replacement theme and see if the white screen condition returns.
  • If you cannot access your admin area, use an FTP client to access your site. Disable your plugins by following step #2 in the plugin's instructions above, and delete the theme entirely. This will force WordPress to use the default WordPress theme. See if the problem persists. If it does, then the problem is likely in your WordPress installation. If the problem does not occur, then install a fresh copy of the theme via FTP, activate it and see if the problem reappears.
  • You may also be suffering from a web server configuration that is set with PHP memory limits too low. If this is the case, it can cause the white screen condition as well. Check with your web hosting service and ask them to increase your PHP memory_limit to at least 64 megabytes. 128 megabytes is recommended.

Other Causes

The following is a list of possible other causes for the white screen condition because they too can cause this error:

  • Blank space in functions.php - This is easy to do if you've been modifying the file. A good way to check is to replace it with the unchanged version of the file and see if the site works.
  • A blank line in wp-config.php - a blank line at the start of this file can bring on the White Death. Check for extra spaces at the end as well.
  • File Permissions - Make sure all the directories are set with permission of 755 and the other files 644. This should not happen because the server should inherit the permissions of the files that get uploaded to the server. But we have seen occurrences where, for example, unpacking a ZIP archive using CPANEL and other interface tools botched permissions.
  • Multiple Plugins - When you're reactivating your plugins, the first one you find that causes the problem may not be the only one. Sometimes its a combination of two or more. So you may think you have the problem solved, but it may still exist and come back in the future.

Tips

  • Check your error logs. A good amount of the time, server logs will show *exactly* what PHP function is causing the issue, and where.
  • Run a PHP validator on the code prior to saving. It will catch a lot of simple mistakes.