WordPress Common Error Troubleshooting: Locating and Fixing 500 Errors, White Screens, and Login Failures

Sudden 500 errors, a completely white site, or inability to access the admin dashboard—while these three symptoms have different root causes, the troubleshooting path is actually quite standard.

First, let’s clarify the scope: this article covers the application layer, specifically issues related to PHP code and the database. If you are encountering 502 / 503 / 504 errors, those belong to the gateway layer between the web server and php-fpm; their causes and solutions are entirely different, so do not mix them up during troubleshooting.

Step 1: Check the Raw PHP Fatal Error

A 500 error and a white screen are essentially the same issue—a fatal PHP error has occurred. The difference is that with a white screen, the error is suppressed, and nothing is displayed on the page. Therefore, the first step is always to enable error display to see what’s happening.

# Memory exhaustion
PHP Fatal error: Allowed memory size of 134217728 bytes exhausted
(tried to allocate 4096 bytes) in /home/www/wp-includes/plugin.php on line 123

# PHP version incompatibility (most common after an upgrade)
PHP Fatal error: Uncaught Error: Call to undefined function my_theme_setup()
in /home/www/wp-content/themes/xxx/functions.php:15

# Syntax error (corrupted file from online editing)
PHP Parse error: syntax error, unexpected ')' in
/home/www/wp-content/plugins/xxx/xxx.php on line 42

# Execution timeout
PHP Fatal error: Maximum execution time of 30 seconds exceeded

# Database connection failure
Error establishing a database connection

# Corrupted database tables
One or more database tables are unavailable. The database may need to be repaired.

Web Server Forwarding Logs

# nginx
FastCGI sent in stderr: "PHP message: PHP Fatal error: ..." while reading response header from upstream

# Apache
AH01071: Got error 'PHP message: PHP Fatal error: ...'

Cause Reference Table

Troubleshooting Commands

# ① Find where the PHP error log is located and check the memory limit
php -i | grep -E '^error_log|memory_limit'

# ② Monitor logs in real-time (both nginx and php-fpm)
tail -f /var/log/php-fpm/www-error.log
tail -f /var/log/nginx/error.log

# ③ Deactivate all plugins — this only disables them, does not delete data, safe to run
wp plugin deactivate --all
# If WP-CLI is not available:
mv wp-content/plugins wp-content/plugins.off

# ④ Switch to default theme to rule out theme issues
wp theme activate twentytwentyfour

# ⑤ Correct site URL (preferred fix for login failures after migration)
wp option update siteurl 'https://example.com'
wp option update home 'https://example.com'
wp option get siteurl

# ⑥ Check database connectivity
wp db check
mysql -u wpuser -p -e 'SHOW DATABASES;'

# ⑦ Fix permissions (WordPress recommends 644 for files / 755 for directories)
find /path/to/wp -type d -exec chmod 755 {} ;
find /path/to/wp -type f -exec chmod 644 {} ;

If you don’t have WP-CLI, here is the SQL equivalent for step ⑤:

UPDATE wp_options SET option_value = 'https://example.com'
 WHERE option_name IN ('siteurl','home');

Configuration Changes

wp-config.php (Must enable during troubleshooting)

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true ); // Writes to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // Do not enable in production; it leaks paths

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

wp-config.php (When URLs do not match reality)

// Higher priority than database values; very useful as a temporary fix after migration
define( 'WP_HOME', 'https://example.com' );
define( 'WP_SITEURL', 'https://example.com' );

wp-config.php (For database table repair)

define( 'WP_ALLOW_REPAIR', true );
// Then visit /wp-admin/maint/repair.php
// Delete this line immediately after use

php.ini / php-fpm pool

memory_limit = 256M
max_execution_time = 300

Decision Tree

WordPress is inaccessible
├─ Shows 500
│ ├─ Enable WP_DEBUG → Check wp-content/debug.log
│ ├─ memory exhausted → Adjust WP_MEMORY_LIMIT / memory_limit
│ ├─ undefined function → PHP version upgrade caused plugin incompatibility → Disable plugin
│ ├─ syntax error → Rollback corrupted files
│ └─ execution time → Adjust max_execution_time
├─ White screen (no output)
│ ├─ debug.log is empty → Log path unwritable → Check php error_log
│ └─ Contains Fatal error → Handle according to 500 branch above
└─ Cannot access admin
   ├─ Redirect loop → siteurl/home mismatch → wp option update
   ├─ Correct password but redirected to login → Cookie domain / cache / security plugin
   └─ 500 → Handle according to 500 branch

Database Errors
└─ Error establishing a database connection
   ├─ Wrong credentials → Verify DB_USER / DB_PASSWORD in wp-config.php
   ├─ MySQL not running → systemctl status mysqld
   └─ Tables corrupted → Repair via WP_ALLOW_REPAIR

Scenario Walkthrough: Renaming a Plugin Prefix Causes Whole-Site White Screen

Symptom: A normally functioning WordPress site suddenly displays a pure white page on both the frontend and backend after routine backend operations, with no error text and an HTTP status code of 500.

1. Note the status code is 500, not 404 → This indicates the request reached PHP; the web service itself is alive.
   The white screen is simply because error display is turned off. This step narrows the scope from “server crash” to “PHP execution error”.
2. Check web service error logs instead of refreshing the page → A white screen provides no clues,
   but the server-side logs record the fatal error: a specific class was not found.
3. Enable debugging to reveal the error → Reproduce the issue, and a clear error appears on the page:
   Fatal error: Class 'XXX' not found, pinpointing the specific file and line number.
4. Determine if your own changes caused it → The last operation was modifying prefix-related configuration,
   causing some caching or concatenation logic to fail to retrieve expected data.
5. Temporarily bypass to restore service → Rename the problematic directory to disable it; the site recovers immediately,
   and you can log into the admin panel. Restore first, then locate the cause—the standard order for handling 500-class incidents.
6. Fix permanently after confirming root cause → Correct the configuration syntax, clear caches, restore the directory, and verify.

# Find the real error: When white-screening, look at logs, not the page
tail -50 /var/log/nginx/error.log
tail -50 /www/wwwlogs/site_error_log.log

# Temporarily enable error display (must revert after fixing)
# In wp-config.php:
# define( 'WP_DEBUG', true );
# define( 'WP_DEBUG_DISPLAY', true );
# define( 'WP_DEBUG_LOG', true ); // Writes to wp-content/debug.log

# Bypass method: Disable the problematic plugin/theme by renaming its directory to restore the site first
mv wp-content/plugins/problematic-plugin wp-content/plugins/_disabled_problematic-plugin
# Process the directory further once the site is confirmed restored

Root Cause: A configuration change caused PHP to reference a non-existent class during execution, throwing a fatal error;
since the site was in production mode with error display disabled, it manifested as a “silent white screen”.

Two key takeaways:

• The primary clue for a 500 white screen is the server-side error log, not the page.
  Refreshing the page will only yield the same white screen, whereas the log usually directly states the file and line number where the error occurred.
• Separate restoration and localization into two steps.
  Disabling suspicious items by renaming directories is the fastest way to stop the bleeding. Its benefit is that it is fully reversible,
  allowing for calm troubleshooting once the site is back online.

8 Common Pitfalls

1. Not checking plugin compatibility before upgrading PHP: This is the #1 cause of 500 errors; old plugins will directly throw undefined function errors on new PHP versions.
2. Editing theme files online: One mistake in the WordPress backend “Theme File Editor” can white-screen the entire site and lock you out of the admin, forcing you to use FTP or server access. It is recommended to disable this feature entirely.
3. Forgetting to turn off WP_DEBUG after troubleshooting: debug.log will grow continuously, and in production, it may leak absolute paths.
4. Enabling WP_DEBUG_DISPLAY in production: Error details, including server paths, are exposed directly to visitors.
5. Not clearing cache after migration: Even after updating siteurl, loops persist, often because a caching plugin or CDN cached the old redirect.
6. Using 777 permissions to “fix” problems: It might work, but it makes site files writable by everyone, which is a major security taboo.
7. Leaving WP_ALLOW_REPAIR enabled after use: repair.php is accessible to anyone; it must be deleted after repairs.
8. Fear of disabling plugins: Deactivating ≠ Deleting; data is safe. Many people delay troubleshooting due to fear, prolonging downtime. This is actually the fastest and safest localization method.

Real Customer Feedback (From Cloud Marketplace Reviews and Consultations for Similar Products)

The following excerpts are taken from real buyer reviews and consultations for similar O&M services on Alibaba Cloud / Tencent Cloud / Huawei Cloud marketplaces (providers include our store and peers, provided solely for reference of real feedback, not fictional tickets from this site):

10***09 2024-03-18 5.0 Convenient and stable | Clean interface | Comprehensive after-sales support (User did not fill in comment content)