Debug Settings

Last updated: February 13, 2026

WordPress provides extensive debugging options for development and troubleshooting. These should be disabled in production.

Primary Debug Constants

WP_DEBUG

define( 'WP_DEBUG', true );

Type: Boolean
Default: false
Purpose: Master switch for WordPress debug mode
Effect When True:
- PHP errors, warnings, and notices are displayed
- Deprecated function notices are shown
- Enables other debug features (WP_DEBUG_LOG, WP_DEBUG_DISPLAY)

WP_DEBUG_LOG

define( 'WP_DEBUG_LOG', true );

PHP errors, warnings, and notices are displayed
Deprecated function notices are shown
Enables other debug features (WP_DEBUG_LOG, WP_DEBUG_DISPLAY)

Custom Log Path

// Log to custom location
define( 'WP_DEBUG_LOG', '/var/log/wordpress/debug.log' );

// Log to a path outside web root (recommended)
define( 'WP_DEBUG_LOG', dirname( __DIR__ ) . '/logs/wp-debug.log' );

WP_DEBUG_DISPLAY

define( 'WP_DEBUG_DISPLAY', false );

PHP errors, warnings, and notices are displayed
Deprecated function notices are shown
Enables other debug features (WP_DEBUG_LOG, WP_DEBUG_DISPLAY)

Recommended Debug Configurations

Development Environment

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );
define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

Production Debugging (Safe)

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/var/log/wordpress/debug.log' );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Production (Normal)

define( 'WP_DEBUG', false );
// Or simply don't define it (defaults to false)

Script and Asset Debugging

SCRIPT_DEBUG

define( 'SCRIPT_DEBUG', true );

Type: Boolean or String (path)
Default: false
Requires: WP_DEBUG must be true
Purpose: Writes errors to a log file
Default Location: /wp-content/debug.log

CONCATENATE_SCRIPTS

define( 'CONCATENATE_SCRIPTS', false );

Type: Boolean
Default: true (when WP_DEBUG is true)
Requires: WP_DEBUG must be true
Purpose: Controls whether errors are printed to the screen
Recommendation: Set to false in production even during debugging

COMPRESS_SCRIPTS

define( 'COMPRESS_SCRIPTS', false );

Type: Boolean
Default: false
Purpose: Forces WordPress to use development versions of CSS and JavaScript files
Effect:
- Loads .dev.js instead of .min.js
- Loads non-minified CSS
- Disables concatenation
Use Case: Debugging JavaScript/CSS issues, developing themes/plugins

COMPRESS_CSS

define( 'COMPRESS_CSS', false );

Loads .dev.js instead of .min.js
Loads non-minified CSS
Disables concatenation

ENFORCE_GZIP

define( 'ENFORCE_GZIP', true );

Loads .dev.js instead of .min.js
Loads non-minified CSS
Disables concatenation

Database Query Debugging

SAVEQUERIES

define( 'SAVEQUERIES', true );

Type: Boolean
Default: true in admin, varies on frontend
Purpose: Controls whether admin scripts are combined into fewer requests
Effect When False:
- Each JavaScript file loads separately
- Easier to identify which script causes issues
Note: Automatically disabled when SCRIPT_DEBUG is true

Using SAVEQUERIES

php

// In your code or a must-use plugin
global $wpdb;

// Display all queries at the bottom of the page
add_action( 'shutdown', function() {
    global $wpdb;
    
    if ( ! defined( 'SAVEQUERIES' ) || ! SAVEQUERIES ) {
        return;
    }
    
    echo '<pre>';
    echo 'Total queries: ' . count( $wpdb->queries ) . "nn";
    
    foreach ( $wpdb->queries as $query ) {
        echo 'Query: ' . $query[0] . "n";
        echo 'Time: ' . $query[1] . " secondsn";
        echo 'Called from: ' . $query[2] . "nn";
    }
    echo '</pre>';
});

Query Monitor Integration

The Query Monitor plugin automatically uses SAVEQUERIES data to display a detailed query log in its toolbar panel.

Error Display Control

WP_DISABLE_FATAL_ERROR_HANDLER

define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );

Each JavaScript file loads separately
Easier to identify which script causes issues

WP_SANDBOX_SCRAPING

define( 'WP_SANDBOX_SCRAPING', true );

Each JavaScript file loads separately
Easier to identify which script causes issues

Environment Type

WP_ENVIRONMENT_TYPE

define( 'WP_ENVIRONMENT_TYPE', 'development' );

Type: Boolean
Default: true
Purpose: Controls JavaScript compression in admin
Effect When False: Scripts are served uncompressed

Usage in Code

// Check environment type
$env = wp_get_environment_type();

if ( 'development' === $env || 'local' === $env ) {
    // Development-only code
}

// Helper functions
if ( wp_is_development_mode( 'plugin' ) ) {
    // Plugin development mode
}

Environment-Based Configuration

css

switch ( wp_get_environment_type() ) {
    case 'local':
    case 'development':
        define( 'WP_DEBUG', true );
        define( 'WP_DEBUG_DISPLAY', true );
        define( 'SCRIPT_DEBUG', true );
        break;
        
    case 'staging':
        define( 'WP_DEBUG', true );
        define( 'WP_DEBUG_LOG', true );
        define( 'WP_DEBUG_DISPLAY', false );
        break;
        
    case 'production':
    default:
        define( 'WP_DEBUG', false );
        break;
}

Development Mode

WP_DEVELOPMENT_MODE

define( 'WP_DEVELOPMENT_MODE', 'plugin' );

Type: Boolean
Default: true
Purpose: Controls CSS compression in admin
Effect When False: Stylesheets are served uncompressed

Usage

// Check if in any development mode
if ( wp_is_development_mode( 'all' ) ) {
    // Any development mode is active
}

// Check specific development mode
if ( wp_is_development_mode( 'theme' ) ) {
    // Theme development mode
}

Additional Debug Constants

WP_LOCAL_DEV

define( 'WP_LOCAL_DEV', true );

Type: Boolean
Default: false
Purpose: Forces gzip compression for scripts in admin

DIEONDBERROR

define( 'DIEONDBERROR', true );

Type: Boolean
Default: false
Purpose: Saves all database queries to $wpdb->queries array
Data Stored Per Query:
- SQL query string
- Execution time
- Calling function/file (backtrace)
Warning: Significant memory and performance impact; never use in production

ERRORLOGFILE

define( 'ERRORLOGFILE', '/path/to/error.log' );

SQL query string
Execution time
Calling function/file (backtrace)

Debug Plugins and Tools

While these settings are configured in wp-config.php, these plugins enhance debugging:

Query Monitor – Comprehensive debugging panel
Debug Bar – Admin toolbar debugging
Log Deprecated Notices – Tracks deprecated function usage
Simply Show Hooks – Displays hooks on page

Complete Debug Configuration Examples

Full Development Setup

// Environment
define( 'WP_ENVIRONMENT_TYPE', 'development' );
define( 'WP_DEVELOPMENT_MODE', 'all' );

// Core debugging
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', true );

// Script debugging
define( 'SCRIPT_DEBUG', true );
define( 'CONCATENATE_SCRIPTS', false );
define( 'COMPRESS_SCRIPTS', false );
define( 'COMPRESS_CSS', false );

// Query debugging
define( 'SAVEQUERIES', true );

// Disable recovery mode for immediate feedback
define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );

Staging Environment

define( 'WP_ENVIRONMENT_TYPE', 'staging' );

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/var/log/wordpress/staging-debug.log' );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Keep scripts minified for realistic testing
define( 'SCRIPT_DEBUG', false );

Production with Logging

define( 'WP_ENVIRONMENT_TYPE', 'production' );

// Log errors but don't display
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/var/log/wordpress/error.log' );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
@ini_set( 'log_errors', 1 );

Security Considerations

Never enable WP_DEBUG_DISPLAY in production – Exposes system information
Protect debug.log – Add to .htaccess: <Files debug.log>Order allow,deny Deny from all</Files>
Move log outside web root – Use custom path for WP_DEBUG_LOG
Disable SAVEQUERIES in production – Memory and performance impact
Disable SCRIPT_DEBUG in production – Slower page loads

View on GitHub