WordPress website or blog administrators and developers will at some point come face-to-face with the dreaded White Screen of Death. This extreme method of informing that something went wrong, coinciding with the lack of information offered is enough to keep webmasters awake at night.
There is probably no doubt that the White Screen of Death may have caused the end to many amateur projects over the years - in particular for those who just started with WordPress. So what can cause a WSOD and what actions can you take should the unthinkable happen to you?
What can cause a White Screen of Death?
A variety of things can bring about the dreaded WSOD. Most typically it's caused by an error within either an active WordPress theme, or a WordPress plugin you are using on your WordPress website. Modifying theme or plugin code from within your browser is asking for trouble as the browser isn't designed to handle any errors that you may produce, which can very likely result in a WSOD.
Never use the WordPress Theme or Plugin Editor
In general, modifying original theme or plugin files through the built-in editor in WordPress isn't recommended, as you could easily break things or cause an error by just missing a single semicolon or else. Small CSS changes for example can be applied by using a built-in custom CSS field within your WordPress theme or by using a suitable plugin. For larger theme customizations you should always use a child theme to be on the safe side and preserve your original theme files.
Especially when modifying PHP code you can begin to run into potentially fatal issues if you are messing with the original code files within the theme or plugin editor. Considering WordPress is developed in PHP, it's very likely that when you're making modifications to a WordPress theme, or a plugin, you will at some point modify PHP code. This is when the editor can bring about some serious issues should you make an error within your PHP code - any error.
Keep in mind, that there is also no Undo function within the WordPress file editor. That means, any fatal PHP error will prevent the editor from reloading, preventing you from rectifying the problem or even freezing you out of your dashboard in the process.
Always test code modifications within your local environment
Using an external text editor (or an IDE) to make code modifications within your local development environment is a much safer method as you're able to quickly undo or amend your code without being on the sharp-end of a WSOD. There are a variety of text editors that you can use:
- Notepad++ (free) is quite possibly the most popular editor available to Windows users. Notepad++ comes with a variety of features such as syntax highlighting, tabbed interface, auto-completion and it is being completely customizable in various ways.
- Sublime Text (free & commercial) is a very popular multi-platform editor. Sublime Text is available for Windows, Mac, and Ubuntu machines and offers some useful features like distraction free mode, multiple selections, instant project switch or split editing.
- Dreamweaver CC (commercial) from Adobe is a comprehensive IDE that offers far more than what any text editor can offer. Its premium features thus come with a premium price tag.
- Eclipse (free) is a multi-platform IDE that offers a comprehensive marketplace of premium grade plugins and other enhancements. It is available for Mac, Windows and Linux.
- Visual Studio (commercial) from Microsoft is a comprehensive IDE that is available for a variety of platforms offering editing and navigation tools as well as debugging and testing tools.
Watch out for whitespace
Keep an eye on whitespace when modifying code. Empty lines at the top or bottom of a PHP file for example can cause a series of issues that will leave you locked out of your WordPress dashboard.
The image above shows you what whitespace can look like within your PHP files, these unnecessary empty lines may cause Headers already sent warnings. As the closing PHP tag is not required in WordPress, and in general is often considered good practice to omit it from the end of your PHP files, anything after the tag, even empty lines, will very likely cause issues in all recent versions of PHP (5+). You can tidy this up quite easily, like so:
Have you updated anything?
You may not even be the responsible party in producing a WSOD, perhaps you have updated an active WordPress theme, or your plugins? Or maybe there have been automatic updates? Being frozen out of your dashboard is a worrying experience but you can quite easily remedy the situation.
Renaming folders
You can use an FTP Client application (or your server's File Manager feature) to connect to your server. That will allow you to rename certain folders within your WordPress installation. If you have just installed or updated a new WordPress theme and are now faced with a White Screen of Death, you should rename that particular theme folder to force WordPress to activate the default theme automatically, granting you dashboard access in the process to do further troubleshooting.
You can carry out a similar process for WordPress plugins, too. If you have recently installed or updated a plugin, you can use an FTP client to access the files on your server and rename that particular plugin folder, deactivating it in the process. You're also able to rename the plugins folder itself, this will deactivate all of your currently active plugins allowing you to login to your dashboard.
In general, renaming folders is a very simple way of forcing WordPress to fall back on its default settings. So rather than deleting your files and folders of WordPress themes or plugins entirely, you can just rename them so WordPress doesn't make use of them anymore.
Host or server issues?
Are your server or hosting providers reporting any intermittent issues? Perhaps you can check their social media channels for the very latest updates? If your host is performing maintenance tasks then this could cause errors on your website if all of the WordPress files aren't correctly loading.
Enabling WP_DEBUG
Enabling the WP_DEBUG constant from within your wp-config.php file will instruct your WordPress installation to begin outputting all errors on-screen. This isn't recommended for live environments, because WP_DEBUG will report every last error regardless of how important you think it is. To enable WP_DEBUG for your WordPress installation, simply open up your wp-config.php file using your preferred text editor and add this line of code:
define('WP_DEBUG', true);
Add the above line of code directly above the line containing:
/* That's all, stop editing! Happy blogging. */
Save and reupload the wp-config.php file to complete the process. You will now be visually informed about all errors that are happening behind-the-scenes of your WordPress website, giving you a far better chance of being able to come up with a working solution to your issue.
Conclusion: Handling White Screen of Death
Next time if you should face a White Screen of Death on your WordPress website, then there are a few things you can check in order to resolve it: watch out for whitespace within your files, check WordPress theme and plugin updates, rename theme and plugin folders by using an FTP client or enable the WP_DEBUG mode to get more information about the error. You also might want to have a look at the following articles which can help you troubleshooting your WordPress website:
