Debugging and Fixing the WordPress “White Screen of Death”
Sometimes your WordPress site will show a blank white screen and nothing else. In the WordPress community, this is known as the WordPress White Screen of Death (WSOD) (a nod to the Blue Screen of Death when a Windows computer has a fatal system error). The White Screen of Death occurs when a request to WordPress fails with a fatal error, usually caused by a PHP or database error.
A Note About Logging
A blank page is shown by default in WordPress because it is configured to hide any fatal error messages as the errors might contain sensitive information that you wouldn’t want people to see when visiting your website. When developing a WordPress website locally, a simple solution to this is to turn on WP-DEBUG in your wp-config.php file to enable debug mode and make WordPress display the errors on the frontend.
define( 'WP_DEBUG', true );
However, this solution isn’t secure for production websites. When you create a site in SpinupWP it enables WP_DEBUG
and configures WordPress to send these errors to the WordPress debug.log
file without showing them on the webpage:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', true );
Unlike other hosting providers, SpinupWP prevents access to the debug.log file in the browser and enables logrotate to prevent the logs filling up your disk.
Check the Logs
When you come across the White Screen of Death on your SpinupWP site, the easiest way to begin to troubleshoot the issue is by checking the WordPress debug.log
file. You’ll need to SSH to your server and use a tool like tail to view the log file:
tail /sites/{domain}/logs/debug.log
By default, tail will output the last 10 lines of the log file. If you want to see more lines you can use the -n
flag to specify a higher number of lines:
tail -n 100 /sites/{domain}/logs/debug.log
You can also use the -f
flag to follow the log file and watch as data is appended to it in real-time:
tail -f /sites/{domain}/logs/debug.log
In most cases, this file should show any errors that are thrown during a WordPress request. This should at least give you an idea of where to look for what might be causing the problem.
If this file is empty or doesn’t provide any useful information, it might also be worth checking the PHP error log (e.g. /var/log/php8.2-fpm.log
) and the Nginx error log (/sites/{domain}/logs/error.log
) for information. Although, it’s very unlikely you’ll find anything in these logs that would be related to the WSOD.
If you don’t find anything in any of the logs, then there are some other things to try to help you figure out what might be causing the issue. When testing the methods below make sure that page caching is disabled for your site otherwise you might see cached results. Also, we recommend SSHing to your server and using the command line to investigate and fix things. However, if you feel more comfortable with a GUI than the command line you can connect to your server over SFTP with an FTP client to achieve the same results in most cases.
Increase PHP Memory Limit
It’s possible that PHP is running out of memory while trying to process a WordPress request. If this is the case, you should see an error like this in your debug.log
file:
Fatal error: Allowed memory size of X bytes exhausted...
By default, PHP is configured with a memory limit of 128MB. You can test this by adding WP_MEMORY_LIMIT
to your wp-config.php file and increasing the memory limit to something higher like 256M
or 512M
:
define( 'WP_MEMORY_LIMIT', '256M' );
This can also be achieved by changing your PHP settings to increase the memory_limit
for your site.
Deactivate WordPress Plugins
A common culprit of the White Screen of Death in WordPress is some bad code in a plugin’s PHP file. A simple way to test this is to disable all of your installed plugins in WordPress and re-enable them one at a time checking your site each time you re-enable a plugin. If you enable a plugin and the WSOD suddenly appears, then you’ve found the culprit plugin.
If you can’t access the WordPress admin (because the error prevents you from logging in, for example) then you can SSH to your server as a site user and use WP-CLI commands to deactivate all of the plugins and re-enable them one at a time.
First, get a list of all your active plugins:
wp plugin list --status=active
+-------------------------------+--------+---------+----------------+-------------+
| name | status | version | update_version | auto_update |
+-------------------------------+--------+---------+----------------+-------------+
| advanced-custom-fields | active | 6.2.9 | | off |
| limit-login-attempts-reloaded | active | 2.26.8 | | off |
| seo-by-rank-math | active | 1.0.217 | | off |
| spinupwp | active | 1.6 | | off |
| wp-migrate-db | active | 2.6.10 | | off |
| amazon-s3-and-cloudfront | active | 3.2.7 | | off |
| wp-ses | active | 1.6.8 | | off |
+-------------------------------+--------+---------+----------------+-------------+
Deactivate them all and check if you’re still getting the WSOD:
wp plugin deactivate --all
Activate one plugin at a time, checking to see if you are getting the WSOD after each one:
wp plugin activate spinupwp
If WP-CLI commands are also failing, as a last resort you can rename the plugins folder in wp-content
to force WordPress to deactivate all of your plugins:
mv wp-content/plugins wp-content/plugins_disabled
You can then create a new plugins folder and move each individual plugin folder across manually to recreate the same testing process as above.
Activate a Default WordPress Theme
If a faulty plugin isn’t causing the problem then it could be some code in your active theme. A simple way to test this is to switch to a default WordPress theme to see if the White Screen of Death disappears.
If you can’t access the WordPress admin, then you can SSH to your server as a site user and use a WP-CLI command to activate a default theme:
wp theme activate twentytwentyfour
If WP-CLI commands are also failing, as a last resort you can rename the themes folder in wp-content
to force WordPress to deactivate your current theme and activate a default theme:
mv wp-content/themes wp-content/themes_disabled
Check File Ownership & Permissions
Sometimes incorrect file ownership and/or permissions might be causing the problem. See our File Ownership and Permissions doc for what the ownership and permissions should be and instructions on how to resolve file ownership and permissions issues.