How to troubleshoot the WordPress white screen (WSOD)

Quick answer: The white screen of death is a fatal PHP error with error display switched off. Enable WP_DEBUG_LOG, read wp-content/debug.log, and deactivate the failing plugin or switch to a default theme via WP-CLI. Since WordPress 5.2, check your admin email too — recovery-mode links land there.

Overview

WSOD is the 500 error’s quieter sibling: PHP died, nothing was rendered, and the browser shows white. Typical triggers are a plugin/theme update with a syntax or compatibility error, a PHP version jump, or memory exhaustion. Modern WordPress often catches it and emails a recovery-mode login link to the site admin address.

Before you start

• SSH + WP-CLI — the fix rarely needs wp-admin.
• Check the admin inbox for a “Your site is experiencing a technical issue” email with the recovery link.

Step-by-step guide

1. Enable logging in wp-config.php and reproduce:

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

2. Read the fatal error: tail -n 30 wp-content/debug.log — it names the file, e.g. .../plugins/some-plugin/init.php on line 42.
3. Deactivate the culprit:

   sudo -u www-data wp plugin deactivate some-plugin

   Theme at fault? sudo -u www-data wp theme activate twentytwentyfour
4. White screen after a PHP upgrade: the error will be a compatibility fatal — update the extension/plugin, or run the site on the previous PHP version until it’s fixed.
5. Only some pages white: raise memory (WP_MEMORY_LIMIT) and look for exhaustion messages in the log.
6. Works again? Re-disable debug display, keep the log setting, and update the failed component properly — on staging next time.

Common issues

• debug.log stays empty: crash precedes WordPress — check the PHP-FPM log; opcode cache can also serve a stale broken file: sudo systemctl reload php8.3-fpm.
• WSOD only for logged-in users: an admin-bar or dashboard plugin — recovery mode or CLI deactivation still works.
• Recovery email never arrives: the VPS can’t send mail — fix outgoing mail later, use WP-CLI now.

When to contact support

WSOD is application-level; support tickets are the channel when the platform is suspect (server unresponsive, filesystem read-only) or you want a platform-side health check while you debug the app.

Frequently asked questions

Why is the screen white instead of showing an error?

PHP hit a fatal error while display_errors is off (correct for production), so nothing rendered. The full error text is waiting in debug.log or the PHP-FPM log.

What is WordPress recovery mode?

Since 5.2, WordPress catches many fatals and emails the admin a special login link that loads wp-admin with the broken extension paused so you can fix it from the dashboard.

The white screen appeared right after updating PHP — what now?

An old plugin or theme is incompatible with the new PHP version. Read the fatal in the log, update or replace that component, or switch the site back to the previous PHP version temporarily.

Related articles

• How to troubleshoot the WordPress 500 error
• How to use staging for WordPress updates
• How to optimize PHP for WordPress
• How to configure WordPress backups

Need a hand? Contact Cloud2Y support →