WordPress WSOD Debugging: 5 Real Crash Scenarios and Minimal Fixes

The WSOD happens when PHP hits a fatal error and stops executing before rendering any output. The page appears blank not because "there's no content," but because PHP crashed before it could output anything.

I've been through 5 WSOD crashes, each with a different root cause. This article doesn't just say "try disabling plugins." It gives you exact commands and minimal fixes for 5 real scenarios.

How WordPress WSOD Protection Works

Since WordPress 5.2, core includes a Fatal Error Recovery Mode. When a plugin or theme triggers a fatal error, WordPress will:

1. Pause the problematic plugin/theme

2. Send a recovery email to the admin address (with a login link)

3. Allow the admin to fix things from the dashboard while the frontend still shows an error to visitors

If you received that email, just click the link and handle it from the admin. But in practice, you often won't get that email — misconfigured mail servers, the SMTP plugin itself crashing, or the error occurring before the mail function loads. The scenarios below cover the "no recovery email" cases.

Scenario 1: White Screen After Plugin Auto-Update

Symptom: Site was fine yesterday, completely white today. You remember a plugin auto-updated overnight.

Troubleshooting Steps:

# 1. Find recently modified plugins
ls -lt /var/www/html/wp-content/plugins/ | head -20

# 2. Deactivate all plugins via WP-CLI
wp plugin deactivate --all --path=/var/www/html

# 3. If WP-CLI also fails, rename the plugins directory
mv /var/www/html/wp-content/plugins /var/www/html/wp-content/plugins.bak
mkdir /var/www/html/wp-content/plugins

If the site recovers after deactivation, it's definitely a plugin issue. Reactivate one by one:

# Restore the plugins directory
rm -rf /var/www/html/wp-content/plugins
mv /var/www/html/wp-content/plugins.bak /var/www/html/wp-content/plugins

# Reactivate one at a time, refreshing the frontend each time
wp plugin activate plugin-a --path=/var/www/html
wp plugin activate plugin-b --path=/var/www/html
# ...until the site whites out again — that's your culprit

Minimal Fix: Disable the offending plugin. Check its "Tested up to" version on WordPress.org. If it's lower than your current WordPress 7.0 version, report the compatibility issue to the plugin author.

Scenario 2: PHP Memory Exhaustion

**Symptom**: Blank page source code is completely empty. Nginx/Apache logs show a 200 status, but the PHP error log contains Allowed memory size of xxx bytes exhausted.

Troubleshooting Steps:

# Check PHP error log
tail -100 /var/log/php8.4-fpm/error.log | grep -i "memory"

# Typical output:
# PHP Fatal error: Allowed memory size of 134217728 bytes exhausted
# (tried to allocate 4096 bytes) in /var/www/html/wp-content/plugins/xxx/xxx.php on line 234

Minimal Fix:

Edit wp-config.php, adding these lines before /* That's all, stop editing! */:

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

Also check PHP-FPM's memory_limit:

# Check current PHP memory limit
php -i | grep memory_limit

# Edit PHP-FPM config (path varies by system)
# Ubuntu: /etc/php/8.4/fpm/php.ini
# Change: memory_limit = 512M

# Restart PHP-FPM
systemctl restart php8.4-fpm

⚠️ Important: If your site normally runs fine at 128M but suddenly exhausts memory, don't just raise the limit. A script is leaking memory. Check the PHP error log for the exact file path and line number — that's your leak source.

Scenario 3: Mass WSOD After PHP Version Upgrade

Symptom: Your host upgraded PHP from 8.1 to 8.4, and now the entire site — including wp-admin — is white.

This is the most common WSOD cause in 2026. PHP 8.4 deprecated several old functions, and many plugins that haven't been updated crash immediately.

Troubleshooting Steps:

# Check current PHP version
php -v

# Enable WP_DEBUG to see the actual error
# Edit wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true);

# Refresh the page, you'll see errors like:
# Fatal error: Uncaught TypeError: strpos(): Argument #1 ($haystack) must be of type string, null given
# in /var/www/html/wp-content/plugins/old-plugin/old-plugin.php on line 45

Minimal Fix:

If your host supports multiple PHP versions, switch back to PHP 8.3 first:

# For Docker setups, edit docker-compose.yml:
# Change php image tag from php:8.4-fpm to php:8.3-fpm
# docker compose down && docker compose up -d

Then audit plugins for compatibility:

# WP-CLI: list all plugins with version info
wp plugin list --fields=name,status,version,update_version --path=/var/www/html

# Check plugins with older versions on WordPress.org for "Compatible up to" info

**Known PHP 8.4 breaking changes**: utf8_encode() removed, strpos()/str_replace() reject null arguments (type tightening), get_magic_quotes_gpc() long gone but still called by legacy plugins. WordPress 7.0 (released May 2026) officially recommends PHP 8.4 as the production version.

👉 Building AI-powered workflow automation? Check out MiniMax Token Plans for cost-effective LLM access: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link

Scenario 4: Frontend White Screen, Backend Works Fine

Symptom: wp-admin works perfectly, but the frontend (what visitors see) is a white screen. This is 90% a theme issue.

Troubleshooting Steps:

# Switch to a default theme
wp theme activate twentytwentyfive --path=/var/www/html

# If frontend recovers, the original theme is the problem
# Check the theme's functions.php
cat /var/www/html/wp-content/themes/your-theme/functions.php | head -50

Common Root Causes:

1. **Theme calls deprecated functions** like get_magic_quotes_gpc()

2. Syntax error in functions.php (missing semicolon or mismatched brackets)

3. Theme incompatible with current WordPress version (Classic Theme breaking under Block Theme mode)

Minimal Fix:

# If using a child theme, check its functions.php first
# Child theme functions.php loads before the parent theme
cat /var/www/html/wp-content/themes/your-theme-child/functions.php

# Create a blank child theme to isolate the issue
mkdir -p /var/www/html/wp-content/themes/test-child
cat > /var/www/html/wp-content/themes/test-child/style.css << 'EOF'
/*
Theme Name: Test Child
Template: your-theme
*/
EOF
cat > /var/www/html/wp-content/themes/test-child/functions.php << 'EOF'

# Check wp-config.php syntax
php -l /var/www/html/wp-config.php

# Typical output:
# PHP Parse error: syntax error, unexpected token ";" in /var/www/html/wp-config.php on line 42

# Backup the corrupted file
cp /var/www/html/wp-config.php /var/www/html/wp-config.php.bak

# Regenerate from wp-config-sample.php
cp /var/www/html/wp-config-sample.php /var/www/html/wp-config.php

# Fill in your database credentials from the backup
grep "DB_NAME\|DB_USER\|DB_PASSWORD\|DB_HOST" /var/www/html/wp-config.php.bak

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);      // Errors written to /wp-content/debug.log
define('WP_DEBUG_DISPLAY', false); // Don't show errors on page
define('SCRIPT_DEBUG', false);     // Use minified JS/CSS