>_ DanFry.net
SysAdmin

Debugging WordPress: 5 Essential Troubleshooting Steps

Published on

#wordpress#debugging#php#sysadmin

If you’ve run into a blank white screen, a cryptic PHP error, or a database connection failure on your WordPress site, you know how frustrating it gets. Whether it happens right after updating a plugin or modifying a theme template, a blank white page (often called the White Screen of Death or WSOD) can lock you out of your admin dashboard completely.

Before panic sets in, take a breath. In almost every situation, the error is caused by a syntax mistake, an incompatible plugin, or a corrupted .htaccess file. With a little methodical troubleshooting, you can diagnose and fix the issue quickly.

Golden Rule of Troubleshooting: Always take a full file and database backup before editing core files or running queries on your server.

Step 1: Disable Recently Installed or Updated Plugins

In over 80% of WordPress crash cases, a conflicting or poorly coded plugin is the direct culprit. If you are locked out of the /wp-admin/ dashboard and cannot deactivate plugins normally, you can disable them instantly using FTP or your cPanel File Manager.

The File Manager Shortcut

  1. Connect to your server using FTP (FileZilla) or open your hosting control panel’s File Manager.
  2. Navigate to your website root directory: public_html/wp-content/.
  3. Locate the plugins folder.
  4. Rename the plugins folder to plugins_old.
# Example via SSH terminal
cd /var/www/html/wp-content/
mv plugins plugins_old

Renaming the folder forces WordPress to automatically deactivate every plugin on your site because it can no longer find their path.

If your website immediately starts loading again, you know a plugin was causing the issue. Rename plugins_old back to plugins, step inside the folder, and rename plugin folders one by one until you isolate the exact plugin triggering the error.

Step 2: Enable WP Debugging in wp-config.php

By default, WordPress hides error messages from display to prevent sensitive server file paths from leaking to public visitors. However, hiding errors makes troubleshooting nearly impossible.

To reveal the actual PHP error message, edit your wp-config.php file located in your site’s root directory.

Copy-Paste Debug Snippet

Open wp-config.php and search for define('WP_DEBUG', false);. Replace it with the following configuration:

// Enable WordPress Debugging Mode
define( 'WP_DEBUG', true );

// Write errors to a log file inside wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Prevent error output from breaking screen layout for public visitors
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

With WP_DEBUG_LOG set to true, WordPress writes all warnings, notices, and fatal errors to a plain text log file at /wp-content/debug.log.

Step 3: Check Server and WordPress Error Logs

Once debugging is enabled, refresh the broken page in your browser. Then check your log files to read the exact error traceback.

What to Look For in debug.log

Open wp-content/debug.log using your file manager or SSH:

tail -n 50 wp-content/debug.log

Look for lines marked Fatal error or Parse error. A typical error message will tell you the precise file and line number responsible:

[10-Mar-2015 01:30:37 UTC] PHP Fatal error: Uncaught Error: Call to undefined function get_header() in /home/user/public_html/wp-content/themes/custom-theme/header.php on line 12

In this example, the traceback points directly to line 12 of header.php inside the active theme. You now know exactly which file to inspect or restore from backup.

Step 4: Reset your .htaccess File and Increase Memory Limits

If your site returns a 500 Internal Server Error or gets stuck in redirect loops, the .htaccess file may be corrupted.

Reset .htaccess to Default

  1. Connect via FTP or File Manager to your site’s root folder.
  2. Rename .htaccess to .htaccess_old to temporarily bypass existing rules.
  3. Create a new empty .htaccess file and paste the standard WordPress rewrite rules:
# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress

Increase PHP Memory Limit

If your site ran out of memory during a heavy update, add this line to your wp-config.php file right above the /* That's all, stop editing! */ comment:

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

Step 5: Verify Database Credentials and Provider Escalation

If your site displays the message “Error Establishing a Database Connection”, your web server cannot communicate with MySQL/MariaDB.

Check wp-config.php Database Settings

Verify that your database credentials match your hosting server settings:

define( 'DB_NAME', 'your_database_name' );
define( 'DB_USER', 'your_database_user' );
define( 'DB_PASSWORD', 'your_secure_password' );
define( 'DB_HOST', 'localhost' );

Common causes of database connection drops include:

  • Incorrect password or username after a hosting migration.
  • MySQL service daemon crashing under high memory load on your VPS.
  • Database table corruption (which can often be repaired via phpMyAdmin or running wp-db repair scripts).

If you’ve verified your credentials and MySQL is unresponsive, check your server error logs or contact your web hosting provider’s support team to verify the database service status.