Debugging, Site Health and Troubleshooting

WP_DEBUG is the main switch. When it is true, wp_debug_mode() sets error_reporting( E_ALL ), so notices, deprecations and _doing_it_wrong() messages are reported. When it is false, WordPress lowers the reporting level to errors, warnings, parse errors and their user-level variants; notices and deprecations are not reported, but warnings still go to PHP’s error log. _deprecated_function() and _doing_it_wrong() only trigger their messages when WP_DEBUG is on.

If wp-config.php does not define WP_DEBUG, WordPress 7.1.3 defines it as true when WP_ENVIRONMENT_TYPE is development or when WP_DEVELOPMENT_MODE is not empty, and as false otherwise. local and staging do not turn it on. The official Docker image always writes define( 'WP_DEBUG', !!getenv_docker('WORDPRESS_DEBUG', '') );, so in containers the WORDPRESS_DEBUG environment variable decides, and the environment type has no effect on it.

WP_DEBUG_LOG only works when WP_DEBUG is true. It accepts two kinds of value:

The lumen-noisy test plugin below produces one warning and one _doing_it_wrong() notice on every request. It is only for reproducing the behaviour on a local copy.

Source: Code Reference: _doing_it_wrong()

With the following settings and the plugin active, a request to the home page creates the log file. Requesting the file over HTTP then returns it to anyone:

Source: WP-CLI: wp config set

The log can contain file paths, SQL, email addresses and anything else a plugin passes to error_log(). On any server reachable from the internet, either point WP_DEBUG_LOG at a path outside the web root or block the file at the web server. Site Health checks for this: with the default path its "Debugging enabled" test reports critical ("Your site is set to log errors to a potentially public file"), and with a path outside ABSPATH it reports recommended. Both results were reproduced on 7.1.3. Moving the log does not delete the old wp-content/debug.log; remove it by hand.

Source: Advanced Administration: Debugging in WordPress

If the file must stay in wp-content, deny it at the web server. The Apache rule below returned 403 for /wp-content/debug.log in the test container (Apache 2.4 syntax; Order/Deny lines from Apache 2.2 tutorials no longer apply). The nginx equivalent, which passed nginx -t on nginx 1.29, is location ~* /wp-content/debug\.log$ { deny all; } inside the server block.

Source: Apache HTTP Server 2.4: Require directive

WP_DEBUG_DISPLAY decides whether errors are printed into the page while WP_DEBUG is on. Its default is true, so define( 'WP_DEBUG', true ); alone prints the warning and notice shown above at the top of every page, before <!DOCTYPE html>, for every visitor. false forces display_errors off; null leaves display_errors as php.ini set it. WordPress always turns display off for REST, AJAX, XML-RPC and JSON requests, so an error there does not corrupt the response body, but it still appears in the log. WP-CLI prints PHP warnings on the terminal whatever the constant says. Site Health rates WP_DEBUG_DISPLAY with WP_DEBUG on as critical, or only recommended when wp_get_environment_type() is local or development.

SCRIPT_DEBUG makes WordPress load the unminified versions of core JavaScript and CSS (.js instead of .min.js). It is useful when a stack trace in the browser console points into a core script, or when testing a patch to core scripts. It defaults to false, except in a wordpress-develop checkout whose version string contains -src. It does not change how plugin assets built with @wordpress/scripts are loaded; those use whatever file the plugin enqueues.

SAVEQUERIES makes wpdb store every query with its duration, the call stack and the start time in $wpdb->queries. It costs memory and time on every request, so enable it only while measuring. A quick check with wp eval:

Source: Code Reference: wpdb

Each entry is an array: SQL, seconds, a comma-separated caller list, start time and custom data. Query Monitor (below) reads the same information and presents it per component, which is easier than reading the array.

On top of the error page, WP_Recovery_Mode::handle_error() decides whether to email a recovery link. In the 7.1.3 source, confirmed by the reproduction below, three conditions must hold:

The email goes to the site’s admin email, or to RECOVERY_MODE_EMAIL if that constant holds a valid address (useful when the admin email is a shared mailbox nobody reads). The recovery_mode_email filter changes its content.

The outputs below come from the stack described on Email Delivery: the official WordPress and MariaDB 11.8 images plus Mailpit, a local mail catcher, with a must-use plugin that sends wp_mail() to Mailpit through phpmailer_init. The differences were the default wp_ table prefix, WP_ENVIRONMENT_TYPE set to local, and no published port: requests were sent from inside the WordPress container with curl -H 'Host: lumenpress.test' http://localhost/.... The site must be installed with a host that contains a dot (wp core install --url=http://lumenpress.test ...), because wp_mail() builds the sender as wordpress@<host> and PHPMailer rejects wordpress@localhost with "Invalid address: (From)", so no recovery email would be sent.

A broken deploy of lumen-catalog is simulated by calling a function whose file was not shipped. The call is inside a closure in the plugin file, so the error is attributed to the plugin:

Source: Plugin Handbook: Header Requirements

After wp plugin activate lumen-catalog, the front end and the login page answer differently:

Source: Mailpit: API v1

The front-end request produced only the short message and no email; the login page request produced the longer message and the email. Opening the link sets a wordpress_rec_* cookie and shows "Recovery Mode Initialized. Please log in to continue." After logging in, Plugins lists Lumen Catalog under Paused (1) with the error message, and the admin bar shows Exit Recovery Mode. The pause is stored in an option named <session id>_paused_extensions and applies only to the recovery session: in the same test, a visitor without the cookie still received HTTP 500 while the recovery session received 200. The fix is to deactivate, roll back or repair the plugin, then exit recovery mode.

The Status tab runs direct tests in PHP when the page loads and async tests through the REST API (wp-site-health/v1/tests/...). Each test returns good, recommended or critical. In 7.1.3 the core tests are:

The loopback test matters more than it looks: when the server cannot request its own URL, WP-Cron (unless a system cron runs it), scheduled posts and the error check of the theme and plugin file editors fail. WP-Cron and Scheduled Tasks covers the cron side.

The Info tab lists the environment in collapsible sections: WordPress, directories and sizes, drop-ins, active and inactive themes, must-use and active plugins, media handling, server, database, WordPress constants and filesystem permissions. Copy site info to clipboard produces a plain-text report for support requests; fields marked private (for example database credentials) are left out of the copy.

Plugins add tests with the site_status_tests filter and Info fields with the debug_information filter. The Lumen Catalog plugin checks that its distributor stock sync (the lp_catalog_sync_stock cron event, described on WP-Cron and Scheduled Tasks) is scheduled and not overdue, and adds a "Lumen Catalog" section to Info:

Source: Code Reference: site_status_tests

A test result needs label, status, badge (label and a color such as blue, green, red, orange, purple or gray), description, actions and test. An async test is added under $tests['async'] with a REST URL in test and, optionally, an async_direct_test callable used when the result is computed without HTTP. The site_status_test_result filter can change any test’s result, including core ones. In an Info field, debug is the value used in the copied report instead of value, and 'private' => true removes the field from it.

WP-CLI 2.12.0 has no bundled site-health command (wp help site-health reports "not a registered wp command"), but any test can be run with wp eval once the admin class is loaded. These runs exercised the three branches of the test above:

Source: WP-CLI: wp eval

WP_Debug_Data::debug_data() (in wp-admin/includes/class-wp-debug-data.php) returns the whole Info tab as an array keyed by section (wp-core, wp-server, wp-database, wp-constants and so on), which ended with the added lumen-catalog section in the test.

"There has been a critical error on this website" means the fatal error handler caught an error. An empty page with HTTP 500 means the handler is disabled, failed itself, or the error happened before WordPress loaded it (for example a parse error in wp-config.php).

A 500 with the server’s own error page, not WordPress’s, usually comes from outside PHP code:

WordPress shows this message, with HTTP 500, when wpdb cannot connect. Both causes below were reproduced, with the matching warnings from debug.log:

With WP_DEBUG and WP_DEBUG_DISPLAY on, the page adds the MySQL error and a checklist ("Are you sure you have the correct username and password?"); with display off, visitors see only the one-line message. A wp-content/db-error.php drop-in replaces this page, for example with a maintenance notice that sends 503 and Retry-After.

Work through the causes in this order:

wp-admin/maint/repair.php runs CHECK TABLE and REPAIR TABLE (and optionally OPTIMIZE TABLE) on the core tables of the current site. It only works with this constant:

Source: WordPress 7.1.3: wp-admin/maint/repair.php

Two facts matter more than the feature itself, and both were checked on 7.1.3:

With shell access, wp db check, wp db repair and wp db optimize do the same work without exposing a page. InnoDB, the default engine, does not support REPAIR TABLE the way MyISAM did; real InnoDB corruption is handled with innodb_force_recovery and a restore from backup.

The error names the limit in bytes and the allocation that failed. The lumen-memtest plugin below reproduces it on a local copy by allocating a string of the requested size:

Source: Code Reference: wp_get_environment_type()

With the image’s memory_limit = 128M, ?lp_memtest=150 failed; after wp config set WP_MEMORY_LIMIT 256M it succeeded:

How the limits work in 7.1.3:

Raising the limit is a workaround. The usual consumers are loops over all posts ('posts_per_page' => -1), large autoloaded options, image processing of huge uploads and runaway recursion in a filter; Query Monitor’s memory figure and memory_get_peak_usage() around suspect code find them.

"Too many redirects" (ERR_TOO_MANY_REDIRECTS) has three usual causes:

Every lockout has a WP-CLI answer that needs no email and no WP_ALLOW_REPAIR:

Source: WP-CLI: wp user reset-password

Typical situations: the password reset email never arrives (an email delivery problem, see Email Delivery); a security plugin has locked the IP after failed logins (deactivate it or clear its lockout table); a lost second factor (deactivate the two-factor plugin for the user); or the account lost its role (wp user set-role). Without a shell, the database route is a new bcrypt or phpass hash written through phpMyAdmin, which is error-prone; prefer the host’s WP-CLI or a support ticket. Delete any temporary administrator account afterwards.

After a switch to HTTPS, browsers block or flag images, scripts and styles still loaded over http://. They come from absolute URLs stored in post content, options and metadata. Check what would change, then run it for real:

Source: WP-CLI: wp search-replace

wp search-replace unserializes PHP-serialized values (the PHP rows) so string lengths stay correct; a raw SQL REPLACE() would corrupt them. guid is skipped because feed readers use it as a permanent identifier. Hard-coded URLs in theme files, CSS and third-party embeds need fixing in code; the browser console names each offending URL. A Content-Security-Policy: upgrade-insecure-requests header is a stopgap, not a fix. Older tutorials suggest SQL UPDATE statements with REPLACE() for this; that breaks serialized options.

When no log line points to a culprit, for example a broken editor, a missing menu item or a slow page, turn extensions off and on until the problem appears. The safe sequence keeps a list of what was active:

Source: WP-CLI: wp plugin deactivate

--skip-plugins is not optional when one plugin throws a fatal error: without it, wp plugin deactivate --all itself loaded the broken plugin and died with the same error. wp plugin deactivate --all does not remember the previous state, hence the file. The script below reactivates the plugins in order and stops at the first one after which the home page stops answering 200. Run it from the WordPress root:

Source: WP-CLI: wp plugin activate

For problems an HTTP status cannot detect, replace the curl check with a manual test after each step. With many plugins, halve the list instead: activate the first half, test, and keep the half that shows the problem; 32 plugins need at most five rounds. A problem that only appears with two specific plugins active together shows up as "No single plugin breaks" and needs the halving approach with both halves combined. On production, Troubleshooting Mode of the Health Check plugin does the same for one user without affecting visitors.