How to Fix WordPress White Screen of Death & Common Errors

TL;DR

The WordPress White Screen of Death (WSOD) and 500 errors are almost always caused by a PHP fatal error, a plugin conflict, an exhausted memory limit, or a corrupted .htaccess file. The fastest path to diagnosis is: enable WP_DEBUG, check your error logs, deactivate all plugins, and switch to a default theme. This guide walks you through each scenario with copy-paste commands for the command line.

Prerequisites

• SSH access to your server (or at minimum FTP/SFTP access)
• A terminal with bash or equivalent shell
• MySQL/MariaDB client access (command line or phpMyAdmin)
• WP-CLI installed (strongly recommended)
• A recent backup of your files and database
• Knowledge of your WordPress installation path (this guide uses /var/www/html as the default)

White Screen of Death

A completely blank white page means PHP encountered a fatal error but error display is suppressed. Your first step is always to make errors visible.

Step 1: Enable WP_DEBUG

Open your wp-config.php and modify or add the following lines before the line that says /* That's all, stop editing! */:

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

Via the command line:

cd /var/www/html

# Enable debug mode via WP-CLI
wp config set WP_DEBUG true --raw --allow-root
wp config set WP_DEBUG_LOG true --raw --allow-root
wp config set WP_DEBUG_DISPLAY true --raw --allow-root

Now reload the page. You should see the actual PHP error message instead of a blank screen. The error will also be written to wp-content/debug.log.

Step 2: Check the Debug Log

tail -50 /var/www/html/wp-content/debug.log

Look for Fatal error lines. They will tell you exactly which file and line number caused the crash.

Step 3: Increase PHP Memory Limit

If the error mentions Allowed memory size exhausted, increase the memory limit:

// In wp-config.php
define( 'WP_MEMORY_LIMIT', '256M' );
define( 'WP_MAX_MEMORY_LIMIT', '512M' );

Also set it in your PHP configuration:

# Find your active php.ini
php -i | grep "Loaded Configuration File"

# Edit it and set:
# memory_limit = 256M
sudo sed -i 's/memory_limit = .*/memory_limit = 256M/' /etc/php/8.2/fpm/php.ini
sudo systemctl restart php8.2-fpm

500 Internal Server Error

A 500 error means the web server encountered an unrecoverable problem. The two most common causes are a corrupted .htaccess and PHP resource limits.

Rename .htaccess

cd /var/www/html
mv .htaccess .htaccess.broken

Now load the site. If it works, regenerate the file by going to Settings → Permalinks and clicking Save, or via WP-CLI:

wp rewrite flush --allow-root

If you need a clean default .htaccess immediately:

cat > /var/www/html/.htaccess << 'EOF'
# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress
EOF
chown www-data:www-data /var/www/html/.htaccess

Increase PHP Limits for 500 Errors

# Check current limits
php -i | grep -E 'max_execution_time|max_input_vars|post_max_size|upload_max_filesize'

# Common fixes in php.ini
sudo tee /etc/php/8.2/fpm/conf.d/99-wordpress.ini << 'EOF'
max_execution_time = 300
max_input_vars = 5000
post_max_size = 64M
upload_max_filesize = 64M
memory_limit = 256M
EOF

sudo systemctl restart php8.2-fpm

Plugin Conflict Debugging

Plugin conflicts are the single most common cause of WordPress errors. The systematic approach is to deactivate all plugins and reactivate them one by one.

Method 1: WP-CLI (Preferred)

cd /var/www/html

# List all active plugins
wp plugin list --status=active --allow-root

# Deactivate all plugins at once
wp plugin deactivate --all --allow-root

# Test the site, then reactivate one by one
wp plugin activate plugin-name --allow-root

Method 2: Rename the Plugins Folder

If WP-CLI is not available or the site is completely unreachable:

cd /var/www/html/wp-content
mv plugins plugins.disabled
mkdir plugins

WordPress will automatically deactivate all plugins because it can no longer find the files. After confirming the site loads, restore and test individually:

# Restore plugins folder
rm -rf plugins
mv plugins.disabled plugins

# Then use WP-CLI or the admin panel to activate one at a time

Method 3: Database Query

wp db query "SELECT option_value FROM wp_options WHERE option_name = 'active_plugins';" --allow-root

# Deactivate all plugins via database
wp db query "UPDATE wp_options SET option_value = 'a:0:{}' WHERE option_name = 'active_plugins';" --allow-root

Theme Issues

If deactivating plugins does not help, the active theme may be the culprit.

Switch Theme via WP-CLI

# List installed themes
wp theme list --allow-root

# Switch to a default theme
wp theme activate twentytwentyfour --allow-root

# If no default theme is installed
wp theme install twentytwentyfour --activate --allow-root

Switch Theme via Database

If you cannot use WP-CLI:

mysql -u root -p wordpress_db << 'EOF'
UPDATE wp_options SET option_value = 'twentytwentyfour' WHERE option_name = 'template';
UPDATE wp_options SET option_value = 'twentytwentyfour' WHERE option_name = 'stylesheet';
UPDATE wp_options SET option_value = 'Twenty Twenty-Four' WHERE option_name = 'current_theme';
EOF

Note: Replace wp_options with your actual table prefix if you changed it during installation.

Database Connection Errors

The dreaded "Error establishing a database connection" message. Follow these steps in order.

Step 1: Verify Credentials in wp-config.php

grep -E 'DB_NAME|DB_USER|DB_PASSWORD|DB_HOST' /var/www/html/wp-config.php

Step 2: Test the Connection Manually

# Extract credentials and test
DB_NAME=$(wp config get DB_NAME --allow-root 2>/dev/null || grep "DB_NAME" /var/www/html/wp-config.php | cut -d"'" -f4)
DB_USER=$(wp config get DB_USER --allow-root 2>/dev/null || grep "DB_USER" /var/www/html/wp-config.php | cut -d"'" -f4)
DB_HOST=$(wp config get DB_HOST --allow-root 2>/dev/null || grep "DB_HOST" /var/www/html/wp-config.php | cut -d"'" -f4)

mysql -u "$DB_USER" -p -h "$DB_HOST" "$DB_NAME" -e "SELECT 1;"

Step 3: Check if MySQL/MariaDB is Running

# Check service status
sudo systemctl status mysql
# or
sudo systemctl status mariadb

# Restart if needed
sudo systemctl restart mysql

# Check if it's listening
ss -tlnp | grep 3306

Step 4: Repair the Database

// Add to wp-config.php temporarily
define( 'WP_ALLOW_REPAIR', true );

Then visit https://yoursite.com/wp-admin/maint/repair.php. Remove the line after repair is complete.

Recovery Mode & Emergency Login

Since WordPress 5.2, fatal errors trigger an automatic Recovery Mode. WordPress emails the admin a special login link.

If You Did Not Receive the Email

# Check the recovery mode keys in the database
wp db query "SELECT * FROM wp_options WHERE option_name LIKE '%recovery%';" --allow-root

# Generate a fresh recovery link (WP-CLI does not support this natively,
# but you can create an emergency admin user)
wp user create emergencyadmin admin@example.com --role=administrator --user_pass='TempSecurePass123!' --allow-root

Emergency Login Script

If you cannot access wp-admin at all, create a temporary emergency script:

<?php
// Save as /var/www/html/emergency-login.php
// DELETE THIS FILE IMMEDIATELY AFTER USE
require_once('./wp-load.php');
$user = get_user_by('login', 'admin'); // your admin username
if ($user) {
    wp_set_auth_cookie($user->ID, true);
    wp_redirect(admin_url());
    exit;
}
echo 'User not found.';

Security warning: Delete this file immediately after use. Anyone who accesses it will be logged in as admin.

PHP Version Compatibility

Running an incompatible PHP version is a frequent cause of WSOD after server upgrades.

Check Current PHP Version

# CLI version
php -v

# Version used by the web server (may differ!)
wp eval 'echo phpversion();' --allow-root

# Or create a phpinfo file temporarily
echo '<?php phpinfo();' > /var/www/html/phpinfo.php
# Visit in browser, then delete immediately
rm /var/www/html/phpinfo.php

Check WordPress and Plugin Requirements

# Check WordPress recommended PHP version
wp core version --allow-root
# WordPress 6.x requires PHP 7.4+, recommends 8.1+

# Check for deprecated function usage in your theme/plugins
grep -rn 'create_function\|mysql_connect\|each(' /var/www/html/wp-content/themes/your-theme/
grep -rn 'create_function\|mysql_connect\|each(' /var/www/html/wp-content/plugins/

Switch PHP Version (Ubuntu/Debian)

# List available PHP versions
ls /etc/php/

# Switch Apache module
sudo a2dismod php7.4
sudo a2enmod php8.2
sudo systemctl restart apache2

# Or switch PHP-FPM pool
sudo systemctl stop php7.4-fpm
sudo systemctl start php8.2-fpm
# Update your Nginx/Apache vhost to point to the new FPM socket

Checking Error Logs

When WP_DEBUG does not reveal enough, check the server-level error logs.

Apache

# Default error log locations
tail -100 /var/log/apache2/error.log
tail -100 /var/log/httpd/error_log

# Find the configured error log for your vhost
grep -r 'ErrorLog' /etc/apache2/sites-enabled/

Nginx

# Default error log
tail -100 /var/log/nginx/error.log

# Find the configured error log for your server block
grep -r 'error_log' /etc/nginx/sites-enabled/

PHP-FPM

# PHP-FPM logs (often the real source of 502/503 errors)
tail -100 /var/log/php8.2-fpm.log

# Check pool-specific logs
grep 'error_log\|slowlog' /etc/php/8.2/fpm/pool.d/www.conf

WordPress Debug Log

# Live-tail the WordPress debug log
tail -f /var/www/html/wp-content/debug.log

Troubleshooting

WSOD only on admin pages

This is typically a plugin that hooks into the admin dashboard. Deactivate plugins via WP-CLI or database (see Plugin Conflict Debugging).

WSOD only on the frontend

Usually a theme issue. Switch to a default theme (see Theme Issues).

Error after WordPress core update

# Force a re-install of core files without touching wp-content
wp core download --force --skip-content --allow-root
wp core update-db --allow-root

"Briefly unavailable for scheduled maintenance"

# A failed update left the maintenance file behind
rm /var/www/html/.maintenance

Too many redirects / redirect loop

# Check and fix site URL settings
wp option get siteurl --allow-root
wp option get home --allow-root

# Fix if they are wrong
wp option update siteurl 'https://yoursite.com' --allow-root
wp option update home 'https://yoursite.com' --allow-root

Permissions issues

# Set correct ownership and permissions
sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;
sudo chmod 600 /var/www/html/wp-config.php

Prevention

1. Automated Backups

Set up daily backups of both files and database. Verify that restores actually work.

# Quick database backup via WP-CLI
wp db export /backups/wordpress-$(date +%Y%m%d).sql --allow-root

# File backup
tar czf /backups/wp-files-$(date +%Y%m%d).tar.gz /var/www/html/wp-content/

2. Staging Environment

Never update plugins, themes, or core on production first. Use a staging site to test changes before deploying.

3. Update Strategy

• Enable automatic minor/security updates (they are on by default)
• Test major updates on staging first
• Update one plugin at a time, not all at once
• Keep a log of what was updated and when

4. Monitoring

# Simple uptime check with curl (add to cron)
curl -sS -o /dev/null -w "%{http_code}" https://yoursite.com | grep -q 200 || echo "Site down" | mail -s "WordPress Alert" admin@example.com

5. Security Hardening

// Add to wp-config.php
define( 'DISALLOW_FILE_EDIT', true );   // Disable theme/plugin editor
define( 'AUTOMATIC_UPDATER_DISABLED', false ); // Keep auto-updates on
define( 'WP_AUTO_UPDATE_CORE', 'minor' );      // Auto-update minor releases

6. Error Logging in Production

Keep debug logging enabled but disable display:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

This writes all errors to wp-content/debug.log without showing them to visitors. Rotate the log file periodically to prevent it from growing too large.