WP_DEBUG Constants | WP Debug Toolkit

WordPress uses a set of PHP constants in wp-config.php to control error reporting and logging behavior. WP Debug Toolkit (WPDT) provides toggle switches, CLI commands, and standalone viewer controls to manage these constants without manually editing files.

The debug constants

`WP_DEBUG`

Enables WordPress debug mode. When set to true, WordPress reports all PHP errors, notices, and warnings instead of suppressing them. This is the master switch — the other debug constants have no effect unless WP_DEBUG is true.

define( 'WP_DEBUG', true );

`WP_DEBUG_LOG`

Writes all PHP errors to a log file. When set to true, errors are written to wp-content/debug.log. You can also set it to a string path to log to a different location:

define( 'WP_DEBUG_LOG', true );
// or
define( 'WP_DEBUG_LOG', '/home/user/logs/debug.log' );

`WP_DEBUG_DISPLAY`

Controls whether PHP errors appear in the browser HTML output. When true, visitors see raw PHP error messages on the page.

define( 'WP_DEBUG_DISPLAY', true );

Warning: Enabling WP_DEBUG_DISPLAY on a production site exposes internal file paths, database details, and code structure to anyone browsing the site. Keep this false on any publicly accessible environment.

`SAVEQUERIES`

Stores all database queries in memory during each page load. WordPress records the query string, execution time, and calling function in the $wpdb->queries array. WPDT uses this for basic query logging.

define( 'SAVEQUERIES', true );

This adds memory overhead proportional to the number of queries per request. On a page that runs 500+ queries, the memory cost is measurable. Avoid leaving this enabled on high-traffic production sites.

Toggling from the admin dashboard

Go to Debug Toolkit > Overview. Each constant has a toggle switch:

Toggle	Constant	Effect
Debug Mode	`WP_DEBUG`	Enables/disables error reporting
Error Logging	`WP_DEBUG_LOG`	Enables/disables writing to `debug.log`
Display Errors	`WP_DEBUG_DISPLAY`	Shows/hides errors in browser output
Save Queries	`SAVEQUERIES`	Enables/disables query recording

When you flip a toggle, WPDT writes the change to wp-config.php immediately. WPDT creates a backup of wp-config.php before any modification, so you can restore the previous state if needed.

Toggling from the standalone viewer

Open the standalone viewer and press K to open the Settings panel. The Debug Constants section contains the same toggles available in the admin dashboard. Changes are applied through the viewer’s API without loading WordPress — useful when WordPress is unresponsive or broken.

WP-CLI commands

WPDT registers wp dbtk debug commands for managing debug constants from the terminal.

Enable debug mode

wp dbtk debug on

Enables WP_DEBUG and WP_DEBUG_LOG. Does not enable WP_DEBUG_DISPLAY.

To also enable display:

wp dbtk debug on --display

Disable debug mode

wp dbtk debug off

Disables WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY.

Check current state

wp dbtk debug status

Outputs a table showing the current value of each constant:

+--------------------+-----------------------------------+
| Setting            | Value                             |
+--------------------+-----------------------------------+
| WP_DEBUG           | ON                                |
| WP_DEBUG_LOG       | ON                                |
| WP_DEBUG_DISPLAY   | OFF                               |
| SAVEQUERIES        | OFF                               |
| Enhanced logging   | OFF                               |
| Log path           | /var/www/html/wp-content/debug.log|
+--------------------+-----------------------------------+

For scripting, use JSON output:

wp dbtk debug status --format=json

[{"Setting":"WP_DEBUG","Value":"ON"},{"Setting":"WP_DEBUG_LOG","Value":"ON"},{"Setting":"WP_DEBUG_DISPLAY","Value":"OFF"},{"Setting":"SAVEQUERIES","Value":"OFF"},{"Setting":"Enhanced logging","Value":"OFF"},{"Setting":"Log path","Value":"/var/www/html/wp-content/debug.log"}]

Production vs development settings

The right combination depends on the environment:

Environment	`WP_DEBUG`	`WP_DEBUG_LOG`	`WP_DEBUG_DISPLAY`
Production	`true`	`true`	`false`
Staging	`true`	`true`	`true`
Development	`true`	`true`	`true`

On production, keep WP_DEBUG_DISPLAY off. Errors are still written to debug.log where you can review them through the viewer or over SSH, but visitors never see raw PHP output. On development and staging environments, enabling all three surfaces errors immediately in the browser during testing.

GridPane hosting

WPDT detects when a site runs on GridPane, which uses secure-debug.php to manage debug constants instead of wp-config.php. When GridPane is detected, WPDT reads from and writes to secure-debug.php automatically. No additional configuration is needed — the toggle switches, CLI commands, and viewer controls all work the same way.

Enhanced query logging

The SAVEQUERIES toggle enables basic query recording built into WordPress. For detailed query analysis — including execution time histograms, N+1 detection, and component-level breakdowns — WPDT offers enhanced query logging through a separate toggle. This installs the db.php drop-in to wp-content/, which captures richer data than SAVEQUERIES alone. See The db.php drop-in for details.