Enable Debug Mode in WordPress

WordPress debug mode reveals PHP errors, notices, and warnings that are hidden in production. It's essential for diagnosing issues with plugins, themes, or custom code.

⚠

Never leave debug mode on in production

Debug mode displays error messages that may reveal file paths, database names, or code details to visitors. Enable it only when actively debugging, and disable it when finished.

Enabling debug mode

Edit wp-config.php in your WordPress root directory. Find the line that says define( 'WP_DEBUG', false ); and replace the debug section with:

// Enable debug mode — show all errors
define( 'WP_DEBUG', true );

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

// Hide errors from visitors (write to log only)
define( 'WP_DEBUG_DISPLAY', false );

// Suppress deprecated notices (optional — reduces noise)
define( 'SCRIPT_DEBUG', true );

With WP_DEBUG_DISPLAY set to false, errors are written to /wp-content/debug.log and not shown to visitors.

Viewing the debug log

# SSH into your server and tail the log
tail -f /home/cpanelusername/public_html/wp-content/debug.log

# Or view the last 100 lines
tail -n 100 /home/cpanelusername/public_html/wp-content/debug.log

Or download it via cPanel → File Manager → navigate to public_html/wp-content/debug.log.

Enabling error display (for local/dev only)

On a local development environment where exposing errors to the screen is acceptable:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', true );  // Show errors on screen
define( 'WP_DEBUG_LOG', false );
@ini_set( 'display_errors', 1 );

⚠

Do not use WP_DEBUG_DISPLAY on a live server

Setting WP_DEBUG_DISPLAY to true on a production server shows error details to all visitors — including database names, file paths, and code excerpts. Use WP_DEBUG_LOG instead.

Common errors and what they mean

Error	Likely cause
Call to undefined function	A plugin or theme function is missing — plugin may not be active or is outdated
Fatal error: Cannot redeclare	Two plugins or theme files defining the same function
PHP Warning: include_once	A file is missing — deleted plugin files or incomplete upload
WordPress database error	MySQL connection issue or a query error — check DB credentials in wp-config.php
Maximum execution time exceeded	A process took too long — increase max_execution_time in PHP settings or optimize the slow query

Disabling debug mode

When you're done, set WP_DEBUG back to false:

define( 'WP_DEBUG', false );

Or remove the debug lines entirely — the default WordPress wp-config.php has WP_DEBUG set to false.

Query Monitor plugin

For more detailed debugging without editing wp-config.php, install the Query Monitor plugin. It shows database queries, PHP errors, hooks and actions, HTTP API calls, and page load performance — all in a browser toolbar panel visible only to logged-in admins.