WordPress Site Health and Debugging — WP_DEBUG, Error Logs and Troubleshooting

In this tutorial, you'll learn to debug WordPress issues — using the Site Health tool, enabling WP_DEBUG, reading error logs, and troubleshooting common problems.

What You'll Learn

• How the Site Health screen works: Status tab and Info tab
• Critical Site Health checks: PHP version, loopback, REST API, HTTPS, file permissions
• Recommended improvements: memory limit, upload size, timeouts
• How to enable WP_DEBUG and related constants in wp-config.php
• How to read debug.log and find the root cause of errors
• Common WordPress errors: White Screen of Death, 500 error, memory exhaustion
• How Query Monitor helps diagnose database queries, hooks, and PHP errors
• Health Check Troubleshooting mode for safe plugin and theme testing
• A debugging cheat sheet for quick reference

Why It Matters

Every WordPress site breaks eventually. A plugin update causes a white screen. A PHP version change triggers deprecated function warnings. A memory limit is too low for a new feature. When your site breaks, you need to fix it fast. Debugging skills transform a panic-inducing problem into a systematic investigation. The Site Health tool and WP_DEBUG give you the information you need to find and fix issues quickly.

Real-World Use

A site owner updates a popular SEO plugin and suddenly sees a white screen on every page. The hosting support team says "it is a WordPress issue." Without debugging tools, the owner has no idea what went wrong. With WP_DEBUG enabled, the error log reveals a PHP fatal error caused by a function name collision between the SEO plugin and a theme function. The owner disables the conflicting plugin, reports the bug, and the site is back online in minutes.

Learning Path

flowchart LR
    A[Multisite Network] --> B[Site Health & Debugging]
    B --> C[Security Hardening]
    B --> D[Performance Optimization]

    style B fill:#38bdf8,color:#0f172a,stroke-width:2px

The Site Health Screen

Navigate to Tools > Site Health in the WordPress admin dashboard. This built-in diagnostic tool checks your site against a set of best practices and reports any issues.

Status Tab

The Status tab shows two categories:

• Critical issues — Problems that need immediate attention (red).
• Recommended improvements — Issues that should be fixed but are not urgent (yellow).

Each issue is explained with a description of the problem, why it matters, and how to fix it.

// Programmatically get Site Health status
require_once ABSPATH . 'wp-admin/includes/class-wp-site-health.php';
$health = WP_Site_Health::get_instance();
$issues = $health->get_issues_counts();
echo 'Critical: ' . $issues['good'] . ', Recommended: ' . $issues['recommended'] . ', Critical: ' . $issues['critical'];

Info Tab

The Info tab shows detailed information about your site grouped into sections:

• WordPress — Version, language, multisite status, site URL, home URL, debug mode status.
• Directory and File Sizes — How much space each directory uses.
• Server — PHP version, server software, MySQL version, server architecture.
• Database — Database type, table prefix length, number of tables.
• Active Theme — Theme name, version, author, template path.
• Active Plugins — Every active plugin with version and author.
• File Permissions — Whether key files and directories are writable.
• Media Handling — Image editing library status, file upload capabilities.

You can copy all this information to your clipboard with one click — useful when asking for support in forums.

Critical Site Health Checks

PHP Version

WordPress recommends PHP 7.4 or higher, with PHP 8.0+ being strongly recommended. Older PHP versions are slower, less secure, and do not receive security updates.

# Check PHP version from the command line
php -v

# Or create a phpinfo file to check from the browser
# Create a file called phpinfo.php in your site root with:

<?php phpinfo();

Delete this file after checking — it reveals sensitive server information.

Loopback Request

WordPress attempts to make an HTTP request to its own site (a "loopback"). This tests that the web server can communicate with itself. If loopbacks fail, some WordPress features break — including Site Health itself, scheduled events (cron), and REST API.

REST API

The REST API must be accessible for the block editor, mobile apps, and many plugins. A failed REST API check often indicates a security plugin blocking REST endpoints or a rewrite rule issue.

HTTPS

WordPress checks that your site uses HTTPS. If your site URL starts with http:// instead of https://, Site Health flags it. HTTPS is no longer optional — search engines penalize non-HTTPS sites, and modern browsers mark them as "Not Secure."

// Force HTTPS for admin and login pages
define('FORCE_SSL_ADMIN', true);

File Permissions

WordPress checks that critical files are not world-writable. Core files should be writable only by the file owner, not by anyone on the server. Overly permissive file permissions are a common security vulnerability.

Recommended Improvements

PHP Memory Limit

The recommended PHP memory limit is 256 MB or higher. If your limit is lower, you may see "Allowed memory size exhausted" errors.

// Increase memory limit in wp-config.php
define('WP_MEMORY_LIMIT', '256M');
define('WP_MAX_MEMORY_LIMIT', '512M'); // For admin area

WP_MEMORY_LIMIT sets the front-end limit. WP_MAX_MEMORY_LIMIT sets the admin area limit, which can be higher because admin tasks (plugin updates, media processing) need more memory.

Post Max Size and Max Upload Size

These settings control how large a file you can upload. The effective limit is the lowest of three values:

// In php.ini or wp-config.php
// PHP sets the maximum POST size
// WordPress adds its own filter
@ini_set('upload_max_filesize', '64M');
@ini_set('post_max_size', '64M');
@ini_set('max_execution_time', '300');

You can also set upload limits using a plugin or a mu-plugin (Must-Use plugin in wp-content/mu-plugins/).

Timeouts

PHP's max_execution_time controls how long a script can run before being terminated. For large plugin updates, media imports, or backup operations, you may need to increase this:

// Increase execution time
set_time_limit(300); // 5 minutes

Enabling WP_DEBUG

WP_DEBUG is a constant in wp-config.php that controls how WordPress reports PHP errors.

// Enable WP_DEBUG in wp-config.php
define('WP_DEBUG', true);

// Log errors to a file instead of displaying them
define('WP_DEBUG_LOG', true);

// Suppress error display on screen (always true in production)
define('WP_DEBUG_DISPLAY', false);

// Use unminified versions of CSS/JS files (for theme/plugin development)
define('SCRIPT_DEBUG', true);

WP_DEBUG (Master Switch)

Sets WordPress into debug mode. When enabled, WordPress starts reporting PHP notices, warnings, and errors that are normally suppressed.

WP_DEBUG_LOG

When set to true, errors are written to wp-content/debug.log. You can also specify a custom path:

define('WP_DEBUG_LOG', '/var/log/wordpress-errors.log');

WP_DEBUG_DISPLAY

Controls whether errors are displayed on the screen. On a production site, set this to false so visitors do not see PHP error messages. On a local development site, set it to true to see errors in the browser.

SCRIPT_DEBUG

When enabled, WordPress uses the unminified (development) versions of its CSS and JavaScript files. This is useful when debugging JavaScript issues in the admin or block editor.

// Complete debug configuration for a development site
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true);
define('SCRIPT_DEBUG', true);

// Complete debug configuration for a production site
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', false);

Never leave WP_DEBUG with display enabled on a production site. Visitors will see PHP error messages that reveal server paths, database structure, and other sensitive information.

Reading debug.log

When WP_DEBUG_LOG is enabled, errors are written to wp-content/debug.log. You can read this file directly:

# Read the last 50 lines of the debug log
tail -n 50 wp-content/debug.log

# Follow the log in real time (add new entries as they appear)
tail -f wp-content/debug.log

# Search for specific errors in the log
grep "PHP Fatal error" wp-content/debug.log

# Count error types
grep -c "PHP Notice" wp-content/debug.log

Understanding Log Entries

A typical debug log entry looks like this:

[27-Jun-2026 14:32:15 UTC] PHP Notice:  Undefined variable: x in /var/www/html/wp-content/themes/mytheme/functions.php on line 45
[27-Jun-2026 14:32:16 UTC] PHP Deprecated:  Function create_function() is deprecated in /var/www/html/wp-content/plugins/old-plugin/plugin.php on line 120
[27-Jun-2026 14:32:17 UTC] PHP Fatal error:  Allowed memory size of 67108864 bytes exhausted in /var/www/html/wp-includes/functions.php on line 500

Each entry contains:

1. Timestamp — When the error occurred.
2. Error Type — Notice, Warning, Deprecated, Fatal error.
3. Error Message — What went wrong.
4. File Path — Which file triggered the error.
5. Line Number — Which line in that file.

Error types from least to most severe:

Common WordPress Errors

White Screen of Death (WSOD)

The browser shows a completely white page. No error message. This happens when PHP encounters a fatal error but error display is disabled.

How to fix:

1. Enable WP_DEBUG and WP_DEBUG_LOG via FTP or file manager (edit wp-config.php remotely).
2. Check debug.log for the PHP fatal error.
3. Disable the plugin or theme mentioned in the error via FTP (rename the plugin folder or switch to a default theme).

# Disable a plugin from the command line when you cannot access admin
wp plugin deactivate problem-plugin

# Or if you do not have WP-CLI, rename the plugin folder via FTP
mv wp-content/plugins/problem-plugin wp-content/plugins/problem-plugin-disabled

500 Internal Server Error

The server returns HTTP 500 without loading the page. This can be caused by PHP errors, .htaccess issues, or server configuration problems.

How to fix:

1. Check the server error log (not debug.log) at /var/log/apache2/error.log or similar.
2. Temporarily rename .htaccess to see if rewrite rules are the cause.
3. Increase PHP memory limit.
4. Disable all plugins by renaming the wp-content/plugins/ folder.

Cannot Modify Header Information

A warning that says "Cannot modify header information — headers already sent." This happens when a PHP file has whitespace or output before a <?php tag, or after a ?> closing tag.

// Wrong: spaces before <?php
  <?php
  // ...

// Wrong: whitespace after closing tag
<?php
  // ...
?>

How to fix: Open the file mentioned in the error and remove any whitespace before <?php or after ?>. Better yet, omit the closing ?> tag in pure PHP files — it is unnecessary and causes this exact problem.

Database Errors

"Error establishing a database connection" means WordPress cannot connect to MySQL. Check:

1. Database credentials in wp-config.php.
2. That the MySQL server is running.
3. That the database user has proper permissions.
4. That the wp_options table is not corrupted.

# Test MySQL connection from the command line
mysql -u username -p -h localhost -D database_name

# If this fails, the issue is with MySQL, not WordPress

Memory Exhausted

"Allowed memory size exhausted" means a PHP script tried to use more memory than allowed. This often happens during media uploads, large plugin updates, or database queries on sites with lots of content.

How to fix:

1. Increase WP_MEMORY_LIMIT in wp-config.php.
2. Deactivate memory-hungry plugins (page builders, backup plugins running on schedule).
3. Optimize the database (clean up post revisions, spam comments, transients).

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

Query Monitor Plugin

Query Monitor is a free plugin that adds a debugging toolbar to your site. It is the most popular debugging tool in the WordPress ecosystem.

What Query Monitor Shows

• Database Queries — Every SQL query with execution time, caller function, and duplicate query detection.
• Hooks & Actions — Every hook that fires on the current page, with callback functions listed.
• PHP Errors — Notices, warnings, and deprecations displayed in context.
• HTTP Requests — Outgoing HTTP requests from your site (useful for finding external API calls).
• Block Editor — Block performance and render information.
• Theme & Template — Which template file is being used, what template hierarchy was followed.
• Environment — PHP version, memory usage, constants, file includes.

// Conditionally load Query Monitor only for administrators
if (!current_user_can('administrator')) {
    add_filter('qm_dispatch', '__return_false');
}

Using Query Monitor to Find Slow Queries

1. Install and activate Query Monitor.
2. Load any page on your site.
3. Open the Query Monitor toolbar at the top of the screen.
4. Click "Queries" to see all SQL queries. Sort by time to find the slowest.
5. Look for queries that are called many times (duplicate or repeated queries).
6. Note the caller — which function or template triggered the slow query.

Health Check Troubleshooting Mode

The Health Check plugin (by the WordPress core team) adds a special mode that lets you test plugins and themes without affecting other users.

How It Works

When you enable Troubleshooting Mode:

1. All plugins are disabled for your session only.
2. The theme switches to a default theme (like Twenty Twenty-Four) for your session only.
3. Other visitors see the site as normal.

This is invaluable for diagnosing issues on a live site. You can determine whether a plugin or theme is causing the problem without taking the site down for everyone.

Steps to Use Troubleshooting Mode

1. Install the "Health Check & Troubleshooting" plugin.
2. Go to Tools > Site Health > Troubleshooting tab.
3. Click "Enable Troubleshooting Mode."
4. Your site reloads with all plugins disabled and the default theme active.
5. Reactivate plugins one by one to find the culprit.

WordPress Debugging Cheat Sheet

Quick Reference

Essential Debugging Constants

// Always use in development
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true);
define('SCRIPT_DEBUG', true);

// Disable caching for development
define('WP_CACHE', false);
define('DISABLE_WP_CRON', true);

// Enable save queries for analysis (use with caution)
define('SAVEQUERIES', true);

The SAVEQUERIES constant stores all database queries in memory so you can inspect them. Only enable this temporarily — it uses significant memory.

wp-config.php Safety Note

Always edit wp-config.php with care. A syntax error here can take your entire site down. Make a backup before editing, and use an FTP client or file manager rather than the built-in WordPress file editor.

Common Mistakes

1. Leaving WP_DEBUG enabled on a production site with display on. Visitors see PHP error messages that include file paths, database queries, and server information. This is a security risk. Always set WP_DEBUG_DISPLAY to false on production sites.

2. Ignoring the debug.log file until it grows to gigabytes. A debug log can balloon quickly on a busy site. Monitor its size and clear it regularly. Better yet, only enable WP_DEBUG_LOG when actively debugging, then disable it.

3. Trying to debug without isolating the problem. When something breaks, disable all plugins and switch to a default theme. If the site comes back, reactivate plugins one at a time. This is the fastest way to find the cause. Trying to read the debug log before isolating often wastes time.

4. Editing wp-config.php from the WordPress admin file editor. If you make a syntax error, you lock yourself out of the admin. Always use FTP, SFTP, or your hosting control panel to edit wp-config.php.

5. Not using a staging environment for testing updates. Updating plugins, themes, or WordPress core on a live site without testing first is risky. Use a staging copy of your site for testing, or use Health Check Troubleshooting Mode to test safely.

Practice Questions

1. Your site shows a white screen after updating a plugin. You cannot access the admin dashboard. What is your first step? Answer: Access the server via FTP or file manager, navigate to wp-config.php, enable WP_DEBUG and WP_DEBUG_LOG, then check debug.log for the fatal error. Alternatively, rename the updated plugin's folder via FTP to force-disable it.

2. Site Health reports a failed loopback request. Why does this matter? Answer: Loopback requests are used by WordPress to test server functionality, run scheduled cron events, and communicate with the REST API. A failed loopback means scheduled posts may not publish and some admin features may not work.

3. Your debug.log is full of "PHP Deprecated" notices from a plugin you use. Should you worry? Answer: Deprecated notices mean the plugin uses functions that will be removed in a future PHP or WordPress version. It is not an immediate problem, but you should update the plugin or find an alternative. Future PHP updates may break the plugin completely.

Challenge: Simulate a broken site scenario. Create a simple plugin that causes a PHP fatal error (use an undefined function call). Activate it on a test site and practice the full debugging workflow: enable WP_DEBUG, read debug.log, identify the problem file, deactivate via FTP, and document each step. Then create a "Hello World" debugging workflow checklist that you could give to a junior developer.

FAQ

Mini Project

Create a debugging lab for a WordPress site:

1. Set up a local WordPress installation with a test theme and a few plugins.
2. Enable WP_DEBUG with logging in wp-config.php.
3. Introduce three artificial problems:
   • Add a PHP notice in a theme's functions.php (reference an undefined variable).
   • Create a plugin that triggers a PHP deprecated function.
   • Set a very low memory limit (define('WP_MEMORY_LIMIT', '32M')) and upload a large image to trigger a memory error.
4. Use the debug log to identify each problem.
5. Fix each problem:
   • Fix the undefined variable by initializing it.
   • Replace the deprecated function with its modern equivalent.
   • Increase the memory limit.
6. Use Query Monitor to confirm the site is running clean.
7. Write a one-page debugging reference sheet with the five most useful commands and techniques you used.

This exercise gives you hands-on experience with real debugging scenarios you will encounter in production.

What's Next

Now that you can debug WordPress issues, move on to Security Hardening to protect your site from common vulnerabilities. Then explore Performance Optimization to make your debugged site run fast.

For more depth, see Maintenance and Backups (keep your site healthy long-term) and PHP Error Handling (advanced PHP debugging techniques).