The WordPress White Screen of Death: A Guide to Recovery

WordPress, like MacOS and even Windows now, has an infamous “White Screen of Death” or “WSOD” for short. The WSOD appears when something goes badly wrong. You’re facing a blank or mostly blank white screen for unknown reasons. Now what?

What is the WordPress White Screen of Death (WSOD)?

You’re unlikely to encounter the “White Screen of Death” (WSOD) on a WordPress site under normal conditions. It’s simply a blank white screen that appears instead of a WordPress site’s public front-end or back-end interface. It means WordPress has crashed and will not load properly.

Since WordPress 5.2 was released in May 2019, WordPress has had a Recovery Mode to protect you from the WSOD. Without Recovery Mode, compatibility issues would be generating a lot of WSODs and frustrated WordPress users. If your server is using a version of PHP or MySQL that’s not supported by a plugin, theme, or extension that you’re installing, instead of breaking your site you will get Recovery Mode. Today, a PHP Out-of-Memory (OOM) error is probably the most common remaining scenario that will bypass the WSOD protection, leaving you with a totally blank screen.

Let’s Ask the WSOD Experts

I checked with WordPress core contributors Marius Jensen, Jon Bossenger, and Alain Schlesser to find out what else might cause a true WSOD nowadays. Marius is the author of the Site Health (now Health Check and Troubleshooting) plugin whose concept and features eventually went into WordPress core. (That’s how we got Recovery Mode and other protections.)

Marius confirmed the only way to make WordPress crash with a totally blank screen is to interrupt PHP’s execution flow so the fatal error handler can’t operate as it should. Breaking the connection between PHP and your HTTP server will achieve that. You won’t get any onscreen troubleshooting feedback. That would be frustrating, but if you’re simply working inside WordPress, installing and configuring plugins, this is unlikely to happen.

GEEK OUT: If you’re interested in some really technical details, Alain Schlesser shared in Post Status Slack that full WSOD conditions are created in three ways. 1) A fatal error is logged but never passed to WordPress’s database abstraction layer because PHP is out of memory or the database is inaccessible for some other reason. 2) In a similar case, PHP code tries to access a restricted memory location resulting in a segmentation fault. Then, according to Alain, the shutdown handler isn’t even triggered because “a bug in PHP itself has killed the PHP process.” 3) The screen output displays only garbage or nothing. Alain says this can happen “if a plugin makes bad use of output buffering. In that case, the application actually ran successfully, it’s just that its output was garbage or non-existent.”

Does the White Screen of Death Mean WordPress Has Been Hacked?

No, a WSOD does not mean the bad guys got you. However, in rare cases, it could be a side-effect of a security breach. If you think hackers have compromised your site, head over to Kathy Zant’s guide, How to Clean a Hacked WordPress Site.

A PHP coding error, a conflict between two or more plugins, or a problem in your server environment are the most likely causes of a WSOD. Fortunately, these are not catastrophes! Your site and its content have not been lost. If you want to, you can fix a WSOD yourself. 

In this article, we’ll go down the list of possible diagnoses and cures for the WSOD. You’ll learn how to bring your WordPress site back to life. You’ll also learn how WordPress works on a deeper level. 

View Preview

The WordPress White Screen of Death: Did I Do That?

Yes. The White Screen of Death is probably the result of something YOU did to your WordPress site.

The cause of a WSOD is usually found in a WordPress plugin you just installed and activated. Or, it could be the result of a recent update. A newly added or updated plugin may be in conflict with another plugin. In this scenario, one plugin is trying to do the same thing as another, or they are acting toward contradictory purposes. 

If a plugin, theme, or malfunctioning PHP code snippets are causing a fatal error, you may get a WSOD. They might contain a syntax error, a bug, or code that isn’t compatible with the PHP version you’re using. If you or your host just upgraded your PHP version — which is a good thing! — incompatible plugins will start throwing errors and could bring down your site with a WSOD. If you are using WordPress 5.2 or higher as you should be, incompatibility issues will activate Recovery Mode, which is a lot more helpful than a true WSOD.

Typically the culprit is whatever has just been changed with a plugin, theme, or custom code.

Since the WSOD is often a response to whatever was changed last (or very recently) that affects your site’s functionality. Review all recent changes. Focus on the changes that seem most likely to cause a problem. If you just installed a new plugin or modified some theme code, those are the first places to look to see what might have gone wrong. 

When WordPress is Only Mostly Dead

All WSODs are not equal, and some are not even true WSODs. 

You may get some kind of error message instead of a completely white screen. It may be a server error message about an HTTP 500 error or a lost database connection. It may be a critical error message from WordPress. Or, your site may load normally for visitors, but when you try to log in, you get the white screen of death. The opposite may be true in other cases: you can log in to the WordPress dashboard, but the public-facing front end of your site is giving everyone a blank screen. 

If your WSOD experience fits any of these descriptions, good news! Your site is only mostly dead. It won’t be hard to revive it.

If you do find yourself facing a completely blank white screen when you visit your WordPress site or try to log in, that’s the true WSOD. You’ll have to dig a little deeper to determine what’s causing it.

WordPress Recovery Mode and the White Screen of Death

Fortunately for anyone faced with a WSOD, Recovery Mode was introduced in WordPress 5.2 to do away with it. Recovery Mode catches a lot of fatal errors and helps you fix them. If you are not using the most recent major release of WordPress core, start there. Get up to date!

Thanks to WordPress’s Recovery Mode, it’s rare to see a completely blank white screen when something goes wrong. You’ll more often see a white window over a gray screen with the following message as of WordPress 6.1:

Older versions of WordPress will show similarly worded messaging like, “The site is experiencing technical difficulties.”

If you browse to a backend /wp-admin URL, there will also be a notice telling you to check your administrator email account for further information:

In other cases, you may see a white screen with bold text describing an “Internal Server Error” with some kind of explanation and guidance for repairing your site. 

Welcome to Recovery

This is Recovery Mode. WordPress is trying to help you help it back on its feet. 

The first thing to do is to check the email address associated with your WordPress Administrator account. WordPress tries to identify fatal PHP errors in all the code it’s executing.

If possible, WordPress will “pause” a plugin or other code that is malfunctioning. WordPress will keep the bad code from executing. Then it will report the details to Administrators by email. 

In the Recovery Mode email, you will find instructions and a temporary link for logging into WordPress under Recovery Mode. (This link is good for 24 hours. After that, a new one will be sent if the site is still experiencing a critical error.) 

PRO TIP: If you don’t get the Recovery Mode email, you may be able to log into WordPress in Recovery Mode anyway by adding the following address to your base site URL when you’re logged in as an Administrator: /wp-login.php?action=entered_recovery_mode.

Here is your opportunity to investigate further. If Recovery Mode has identified a specific plugin as the cause of your WSOD, deactivate it. This will bring your site back up for everyone. Then you can investigate any known issues for this plugin. Check to see if there’s an update for it. Reach out to the people responsible for maintaining it.

Not Every White Screen of Death is the Same in WordPress

In a few exceptional cases, something has gone wrong elsewhere in WordPress or your server environment. An update or install process may have stalled, leaving your site stuck in maintenance mode. You, your hosting provider, or a plugin you’ve installed may have modified php.ini or .htaccess files with unexpected results. Your existing environment may not support the requirements of a newly installed plugin. 

WordPress Recovery Mode isn’t able to cope with these situations, but it will produce visible error messages on an otherwise white screen. The front end of your site may be inaccessible, but the admin login screen and back-end interface may be operating normally.

These are not true WSOD situations, but they’re just as annoying. Usually, one of the following conditions causes them:

1. You’re Stuck in Maintenance Mode

While updating WordPress core, plugins, or themes, WordPress goes into “Maintenance Mode.” Browsing to any part of the site will show a gray screen with a white message window that says: 

Sometimes this doesn’t clear up in a minute, but quality-managed WordPress hosting will notice and fix this with an automated process. If you’ve waited a few minutes with no change, you can get out of Maintenance Mode by deleting the .maintenance file in your web/application root folder where WordPress is installed. (To see it, you may need to enable viewing “invisible” files headed by a period in the filename.)

When there is no .maintenance file present your site will load as expected.

2. You’ve Reached a File Upload or Post Size Limit

Your site may time out to a white screen in an upload, post-publishing, or form submission process because you’re sending too much data.

Solution: Increase your post content limit in wp-config.php:

ini_set('pcre.recursion_limit',20000000);
ini_set('pcre.backtrack_limit',10000000);

Solution: Increase your file upload and post size limit in php.ini:

upload_max_filesize = 256M
post_max_size = 256M

Extending the time (in seconds) before a post or any form submission times out may help too. It’s also possible for you to increase the time PHP has to execute scripts and parse the input. Additionally, we can increase the number of variables that are allowed in a form submission. Finally, we can specify the time limit after which PHP will treat submitted data as garbage:

max_execution_time = 300
max_input_time = 300
max_input_vars = 1000
session.gc_maxlifetime = 1000

Or in .htaccess, httpd.conf, or virtualhost:

php_value upload_max_filesize 256M
php_value post_max_size 256M
php_value max_execution_time 300
php_value max_input_time 300
php_value max_input_vars 1000
php_value session.gc_maxlifetime 1000

Or in a custom code snippet for WordPress or a theme functions.php file:

@ini_set( 'upload_max_filesize', '256M' );
@ini_set( 'post_max_size', '256M' );
@ini_set( 'max_execution_time', '300' );
@ini_set(‘max_input_time’, ‘300’ );
@ini_set(‘max_input_vars’, ‘1000’ );
@ini_set(‘session.gc_maxlifetime’, ‘1000’ );

The memory and time values in these parameters are just recommendations. To make sure they’re working and to check their current values, use the Site Health tool in your WordPress Admin interface. 

Along with Recovery Mode, WordPress 5.2 introduced the Site Health tool. It’s very helpful for diagnosing problems and getting technical information about your site settings and server environment. Find it in your Admin Menu under Tools > Site Health. You may also benefit from the extended features in the Health Check and Troubleshooting plugin for WordPress.

3. PHP is Out of Memory

PHP is the server-side scripting language WordPress core is based on. A WSOD appears if there is not enough memory for PHP to run WordPress and your active plugins. You may see this indicated in an error message or log.

Depending on your hosting plan, you may be able to increase the PHP memory limit for all applications on your server or a specific instance of WordPress. Ask your host’s technical support team for help if you’re not sure what to do.

wp-config.php

Normally, adding the following setting to your wp-config.php file in your WordPress folder will set the front-end memory limit for WordPress to 256 MB in this example:

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

128 to 256 MB should be more than adequate. You may also be able to define the maximum or back-end memory allocated to PHP (256 MB in the next example too) by adding the following line to wp-config.php as well:

define(‘WP_MAX_MEMORY_LIMIT’, ‘256M’);

The second number is the maximum memory limit defining the total memory PHP has available for itself. The first number is the memory for WordPress running within that larger PHP limit. The maximum PHP memory limit should be equal to or higher than the WordPress application memory limit. 

php.ini

Another way to define the PHP maximum memory limit is with a setting in a php.ini file located in your WordPress folder:

memory_limit = 256M

Be sure there is no semicolon at the beginning of the line! And take note, php.ini will only impact the instance of WordPress (or any other PHP application) running in or under the folder the php.ini file is located in. If you have access to your server or web root, a php.ini file located there will govern the environmental settings for all PHP applications unless they have their own php.ini file that specifies different conditions.

.htaccess

A third way to define the PHP memory limit is through the .htaccess file in your WordPress folder if you are using Apache or Litespeed as your HTTP server. Like the examples above, .htaccess needs to have an uncommented line like this to set a maximum PHP limit of 256 MB:

php_value memory_limit 256M

Errors in the syntax of application and server settings in wp-config.php, php.ini, and .htaccess can also cause a WSOD. You may need to manually correct or replace them with their original defaults if they are breaking your site. If you are using an Apache or Litespeed web server, the .htaccess file that governs how they operate can be changed by many WordPress plugins. Errors introduced in any of these files can bring up a WSOD and bring down your site.

4. Your HTTP Server is Crashing

HTTP (or its encrypted, secure form HTTPS) is the hypertext transfer protocol that makes a web server a web server. It is how servers serve web pages (HTTP documents) to clients (like browsers) upon request.

Commonly used HTTP servers for WordPress sites are Apache, Litespeed, and NGINX. Their error screens look slightly different and may vary in the ways browsers display them, but they all report the same HTTP error codes. 

An HTTP 500 error, also known as an Internal Server Error, indicates that there is an unexpected issue with your HTTP server that is preventing it from fulfilling HTTP requests. Other 5xx server error codes, especially 502 (Bad Gateway), 503 (Service Unavailable), and 504 (Gateway Timeout), indicate your server is overloaded or inaccessible. The 500 internal error is a catch-all for breakdowns on the server that stop it from returning the requested page/document. 

Your browser may provide its own unique take on HTTP error screens, and it may display special error codes of its own. Google Chrome (and other Chromium-based browsers) lists and explains all its own error codes internally if you browse to chrome://network-errors/ in your address bar while using Chrome.

Server-Side Problems

Commonly used HTTP server software for WordPress sites includes Apache, Litespeed, and NGINX. Many WordPress hosts use them with caching to maximize performance.

If a hard refresh of your browser or clearing your browser cookies and cache does not eliminate the 500 error screen, you could be picking up some bad server-side cache files. Server-side caching can cause a lot of confusion when it’s not working well, so you should also try clearing it. Your hosting control panel or WordPress admin interface may have cache-clearing controls. 

Common causes of an HTTP 500 error can include the following server-side conditions:

1. The PHP memory limit has been exceeded.
2. Other PHP errors when PHP is not set to display errors. 
3. Insufficient permission to access server files and folders.
4. Syntax errors in the .htaccess configuration file.

We’ve already addressed PHP memory limits and how to increase them. We’ll dig into PHP debugging in the next section below. 

Incorrect permissions shouldn’t happen on modern, manage WordPress hosting, but they are common on traditional shared hosting. Files should be set to 664 or 644, folders should be set to 775 or 755, and wp-config.php should be set to 660, 600, or 644. Learn more about changing file permissions at WordPress.org.

If you’ve made changes to your .htaccess file or are using a plugin (often or caching) that changes it, you may need to review it for errors, restore it, or recreate a new, working .htaccess file. Learn more about .htaccess at WordPress.org.

Client Side Problems

HTTP 500 errors can also be caused on the client side (in your browser) by other conditions:

5. Incorrect browser settings.
6. A corrupt cache.
7. Corrupt JavaScript files that run in your browser.
8. Internet connectivity issues.

Try loading your site in a different browser to eliminate your current browser as the problem. If you do have a browser issue, try resetting it to its default settings. Disable any browser extensions or plugins you’ve installed to see if they are interacting badly with your site. 

If your problem is related to bad cache files, the uncached WordPress admin area may still be accessible to you. If you can still log into the WordPress admin interface, you may be able to use cache-clearing switches there or try the additional troubleshooting steps discussed below.

It’s also possible that an HTTP 500 error can be caused by a problem with the database, an issue with a plugin or theme in a WordPress site, or a problem with WordPress itself.

To troubleshoot an HTTP 500 error, you should turn on error logging for your HTTP server and PHP. Then check what errors appear in both. You might also check and potentially increase the PHP memory limit, deactivate plugins, and switch to a default theme to see if any of these actions bring your site back up.

We’ll go into these steps in more detail below. If following them doesn’t do away with the 500 error, contact your web host’s support team for further assistance.

When WordPress is Truly Dead 

If you are getting a completely white screen on every front and back end page of your WordPress site with no error feedback visible at all, that’s the full WSOD experience. You can get some error messages and diagnostic information if you know how to access your PHP error logs and HTTP server logs. Turning on PHP debugging for WordPress is another option. Your host may have some tools to make debugging more accessible to you. But if that’s not the case, you can simply go down this list of cures for the common WSOD until you find your solution.

A Master Checklist for Troubleshooting and Fixing WordPress’s White Screen of Death

To fix the WordPress White Screen of Death, going through the following steps will lead you to a solution. They are organized in order of the most common WSOD causes as I’ve experienced them, but you can try them in any order. 

It makes the most sense to prioritize the solutions that seem to be most relevant to your particular situation. 

The error logging and debugging step (#2) is the most technical, but it is thorough and will always tell you what is causing WordPress to terminate.

I’ve provided links to a few free plugins that can be useful diagnostic and repair tools. You may also find iThemes Security especially helpful for its database scan and repair feature, as well as its file change detection. It even has server tools for a deeper look at your server settings and capabilities.

In the last resort, a good, recent backup will bring your site back online in its last-known good state. Backup Buddy is the best plugin for this role.

Clear Your Browser Cache and Cookies

Cached pages of your site in your browser and on your server can show you something different than what is actually happening. Let’s make sure you are seeing what WordPress is showing brand new visitors to your site.

First, clear your browser’s cache and cookies. This will end your user session if you are logged into WordPress or any other site so you’re looking at it like any other visitor.

Next, use your hosting panel and WordPress admin (if it’s available) to clear any server-side caching your host and WordPress cache plugins are creating. Try turning off all your site and server caching. Perform a hard refresh in your browser. If that clears up the problem, the problem may be that you have cache settings activated that aren’t working on your system. Through a process of elimination, you can identify which ones work and which ones don’t.

2. Look for PHP Errors

PHP code in WordPress core, themes, or plugins can generate a fatal error that will make WordPress give up the ghost with a White Screen of Death. 

To get more information about fatal PHP errors and what is causing them, you can turn on PHP error reporting and send it to the screen, a log file, or both. Fatal errors will likely point to the source of the WSOD.

As a PHP-based web application, WordPress has its own diagnostic reporting system for debugging that helps you take advantage of PHP’s error-logging functions. To turn it on and control it, make sure there’s a line in wp-config.php that says:

define(‘WP_DEBUG’, true);

You may need to add it or change the value from false to true. This tells WordPress to turn on PHP debugging.

You can also take a shortcut by installing and activating the WP Debugging plugin. It will turn on PHP debugging for WordPress without you having to modify wp-config.php directly yourself.

The additional wp-config.php parameters shown below will print the debugging output to the screen as HTML and a file named “error_log” by default:

define( 'WP_DEBUG_DISPLAY', true );
define( 'WP_DEBUG_LOG', true );

It may also be helpful to force WordPress to use the non-optimized versions of its CSS and JavaScript dependencies on the off-chance they are causing a problem:

define( 'SCRIPT_DEBUG', true );

The Debug Bar plugin is a useful additional and complementary tool. It will show you debugging data in a nice interface. 

For this to happen, in php.ini there must be a line that gives the error_reporting constant a value other than NONE, like error_reporting = E_ALL. There should not be a semicolon heading this line; that makes it a comment rather than an active setting. Note you will get every PHP error, warning, and notice if you use E_ALL. Use a different value like E_ERROR to log only fatal runtime errors that cause WordPress to crash.

3. Check for Theme and Plugin Conflicts

Debugging for PHP errors as described in the previous step should point you to a clear theme or plugin file as the source of your WSOD. You can also close in on it with a less technical process-of-elimination approach.

Troubleshooting Themes

The White Screen of Death is often caused by conflicts between WordPress themes and/or plugins. To identify the conflict source/s, you can try deactivating all of your plugins and switching to the current, unmodified default theme packages with WordPress core, like Twenty Twenty-Three. 

Start with the theme — it’s the simplest to test. If switching your active theme to a known-good, unmodified default theme brings your site back online, you know your problem is in the theme you’ve been using. 

Take a look at your theme’s functions.php file if it has one. If you recently changed it, that’s a likely source of your woe. The functions.php file is where custom functional code is added for use with a theme when it’s activated. Bad code and syntax errors here will give you a WSOD.

Troubleshooting Plugins

You can deactivate plugins without access to the WordPress admin via the command line/SSH or SFTP simply by moving the plugin folders out of the /wp-content/plugins/ folder temporarily. My practice is to create a plugin subfolder called “A” so it appears first in the alphabetically sorted /plugins directory. Then I move all the other plugin folders into “A.” 

Once you’ve done this, reload your site. WordPress will behave as if the plugins have all gone away. They’re still installed but deactivated. If the White Screen of Death goes away, you can try reactivating your plugins and theme one by one, refreshing your home page each time to see which one causes your site to crash.

Meks Quick Plugin Disabler is a handy tool that quickly disables all active plugins and then re-enables them from inside the WordPress admin at your command.

4. Repair Corrupt Core Files

Your WSOD may be the consequence of corrupted core WordPress files. While this is unlikely, it’s simple to quickly reinstall the latest version of WordPress with one click in the WordPress Dashboard Updates area. This won’t harm any of your plugins, themes, or existing content, so it’s a good, easy way to confirm your core files are fine. 

If none of the above steps help, the WSOD may be caused by a problem with your server environment that’s beyond your reach. In this case, you may need to contact your hosting provider for assistance. As a last resort, you can also roll your site back to a “last known good” state by restoring a backup.

How to Prevent a WSOD — Advice for WordPress Site Owners and Builders

WordPress was working just fine — and then all of a sudden you got the White Screen of Death!

This is probably because YOU changed something critical to WordPress’s functioning. 

If you’re using a solid managed WordPress hosting account with Liquid Web or Nexcess that’s properly configured with sufficient resources for the things you’re doing with it, 99% of the ways you can break WordPress with a WSOD can be avoided.

The problem is site owners don’t avoid these practices!

What Not to Do

1. Cowboy Coding. Adding or editing functional code on a live site via SFTP, the command line, or code editors and script inserters inside the WordPress admin. One small mistake will bring the site down. Changing configuration files like .htaccess and wp-config.php can also bring a site down. Work on a local test or live (but not public) staging site instead. 
2. Installing Dubious Themes, Plugins, and Extensions. Installing low-quality or even nulled software to a live site is an invitation for trouble. Simply adding too many things at once can make it hard to determine what finally is a breaking change. Similar to cowboy coding, installing new code products into a live site is risky. Test well on a private local or staging site first. 
3. Complicated Caching. There are several kinds of server-side caching your host may offer that may not play well with all caching and performance optimization plugins. When you are implementing new caching methods or settings, test carefully on local and staging environments before implementing changes to a live site. 
4. Updating Everything at Once. You can batch-update many themes and plugins all at once. Normally this works, but if your server times out, you may get stuck in maintenance mode. Also, newly updated code can introduce new bugs, conflicts, or compatibility issues. If this happens and your site goes down, it will be harder to identify the source of the problem. It could be any number of items if you updated multiple themes, plugins, and extensions all at once. Updated code can be tested locally and on live staging sites before rolling it out on your main public site. 

Tips for a Life Without WSOD

The WSOD can happen to any WordPress site, but it shouldn’t be cause for alarm. Following the tips in this guide can help you identify the problem and fix it quickly before your site visitors ever notice. 

Problems with a WordPress site underscore the importance of proper maintenance and care. Better than reacting to WSODs, you can learn to work on WordPress in a way that will never expose your visitors to error messages and blank screens.

Make your changes carefully and deliberately. Deal with your potential WSODs in a local test or staging environment. These are standard tools and features for most managed WordPress hosts today. If you follow these basic, best practices you won’t have to worry about the WordPress White Screen of Death.