The Developer’s WordPress Troubleshooting Protocol

1. The Diagnostic First Step: WP_DEBUG

Before you touch a single plugin, you need to see the actual PHP error. The “White Screen of Death” is usually just a suppressed fatal error.

• The Fix: Edit your wp-config.php and enable logging:PHPdefine( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false );
• Pro Tip: By setting WP_DEBUG_DISPLAY to false, you keep the errors out of the public eye while writing them to /wp-content/debug.log for your review.

2. Resolving 504 Gateway Timeouts

A 504 error usually means NGINX is waiting for PHP-FPM to finish a task, but PHP is taking too long.

• The Diagnosis: Check the NGINX error log. You’ll likely see “upstream timed out.”
• The Fix: Increase the fastcgi_read_timeout in your NGINX server block and match it with the max_execution_time in your php.ini.
• The Root Cause: Often, this is caused by a slow third-party API call or a massive database query that isn’t indexed.

3. Fixing “Error Establishing a Database Connection”

This is rarely a “random” error. It means the PHP process cannot authenticate with MySQL.

• The Checklist:
  1. Check the Service: Is MySQL running? (sudo systemctl status mysql)
  2. Check Credentials: Are the DB_USER and DB_PASSWORD in wp-config.php correct?
  3. Check the Prefix: Did the database prefix change during a migration?
  4. Check Disk Space: If your VPS disk is 100% full, MySQL will crash and refuse to start.

4. Memory Exhaustion Errors

“Allowed memory size of X bytes exhausted.” This happens when a process tries to exceed the allocated RAM for PHP.

• The Fix: Increase the limit in wp-config.php: define( 'WP_MEMORY_LIMIT', '256M' );.
• The Structural Fix: If this keeps happening, use a profiler like Query Monitor or Xdebug to find the specific plugin or function that is leaking memory.

5. Permission and Ownership Conflicts

If you can’t upload images or update plugins, your server’s file ownership is likely mismatched.

• The Fix: Ensure the web server user (www-data) owns the files.Bashsudo chown -R www-data:www-data /var/www/html find . -type d -exec chmod 755 {} \; find . -type f -exec chmod 644 {} \;
• The “Internal” Fix: Check if DISALLOW_FILE_MODS is set to true in your config, as this will block all updates regardless of permissions.