Enabling WordPress Debug Mode the Right Way

WordPress debug mode is the single most useful diagnostic tool available to any site owner dealing with an error — and it is one of the most underused. By default, WordPress silences PHP errors to prevent them from being displayed to site visitors, which is the correct behaviour for a live site. But that same silence means that when something goes wrong, you get a blank page, a vague 500 error, or a generic critical error message with no indication of what actually failed. Enabling WordPress debug mode converts that silence into specific, actionable information: the exact file, the exact line, and the exact type of error that caused the failure. I use WordPress debug mode as my first diagnostic step on virtually every WordPress problem that is not immediately obvious — it almost always provides the missing piece of information that makes the fix clear. This guide covers every aspect of enabling, reading, and safely managing WordPress debug mode on both live sites and development environments. For a broader walkthrough, our Complete Guide to WordPress How is a good next read.

What WordPress Debug Mode Actually Does

WordPress debug mode works by changing the way PHP error reporting behaves during WordPress execution. PHP has its own error reporting system that generates messages for fatal errors, warnings, and notices. Normally, WordPress suppresses these messages — the WP_DEBUG constant is set to false by default, which tells PHP to keep quiet regardless of what errors occur. When WordPress debug mode is enabled, WordPress lifts this suppression and allows PHP errors to surface through the error reporting path you configure.

The key to understanding WordPress debug mode is that there are three separate behaviours you can control independently through three separate constants in wp-config.php:

// WP_DEBUG: Master switch for WordPress debug mode
// true = enable error reporting; false = suppress all errors (default)
define( 'WP_DEBUG', true );

// WP_DEBUG_LOG: Write errors to wp-content/debug.log file
// true = errors written to file; false = no log file created (default)
define( 'WP_DEBUG_LOG', true );

// WP_DEBUG_DISPLAY: Show errors in the browser
// true = errors printed on page (dangerous on live sites)
// false = errors logged but not displayed (safe on live sites)
define( 'WP_DEBUG_DISPLAY', false );

The combination that matters most for safely using WordPress debug mode on a live site is: WP_DEBUG = true, WP_DEBUG_LOG = true, WP_DEBUG_DISPLAY = false. This configuration activates error reporting and writes every error to the debug log file without exposing any error details to site visitors. Visitors see the same user-facing error messages they would without WordPress debug mode active; you gain access to a detailed log that tells you exactly what went wrong. This is the only configuration appropriate for running WordPress debug mode on a publicly accessible production site.

How to Enable WordPress Debug Mode Safely

Enabling WordPress debug mode requires editing one file — wp-config.php — which lives in the root of the WordPress installation. This file contains WordPress’s core configuration constants and is accessible via FTP, SFTP, SSH, or the hosting file manager. The edit is small and reversible, and the whole process takes under two minutes.

1. Connect to your server via FTP (FileZilla, Cyberduck) or open the File Manager in cPanel, Plesk, or your hosting control panel
2. Navigate to the WordPress root directory — the same folder that contains wp-login.php, wp-settings.php, and the wp-content folder
3. Download a copy of wp-config.php to your local computer as a backup before making any changes
4. Open wp-config.php in a text editor. On Mac, use TextEdit in plain text mode. On Windows, use Notepad or Notepad++. Never use a word processor (Word, Google Docs) — they alter quotes and formatting in ways that break PHP
5. Find the existing WP_DEBUG line — it typically reads define( 'WP_DEBUG', false );. It is usually near the bottom of the configuration constants, above the line “That’s all, stop editing!”
6. Replace the existing WP_DEBUG line with the three-line WordPress debug mode configuration:

   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   define( 'WP_DEBUG_DISPLAY', false );

7. Save the file and upload it back to the server, overwriting the existing wp-config.php
8. Reload the page that was showing the error — WordPress debug mode is now active and writing errors to wp-content/debug.log
9. Connect via FTP and download wp-content/debug.log to read the logged errors

If wp-config.php does not contain a WP_DEBUG line at all — which can happen on older WordPress installations — add the three-line block directly above the line “That’s all, stop editing!” rather than replacing an existing line. WordPress debug mode will activate on the next page load once the constants are present in the file.

Reading the WordPress Debug Log to Diagnose Errors

The WordPress debug mode log file at wp-content/debug.log is a plain text file that records every PHP error, warning, and notice that occurred during WordPress execution. Each entry follows the same format: a timestamp in square brackets, the error level, the error message, and the file path with line number. Learning to read this format efficiently makes WordPress debug mode diagnosis significantly faster.

A typical fatal error entry in the debug log looks like this:

[13-May-2026 14:23:45 UTC] PHP Fatal error: Uncaught Error: Call to undefined function
get_plugin_data() in /home/user/public_html/wp-content/plugins/myplugin/myplugin.php:47
Stack trace:
#0 /home/user/public_html/wp-settings.php(456): include()
#1 /home/user/public_html/wp-config.php(90): require_once()

From this single log entry, WordPress debug mode has revealed: the error type (PHP Fatal error), the specific error (calling an undefined function), the function name (get_plugin_data()), the plugin file causing it (myplugin.php), and the exact line (47). This is everything needed to diagnose the problem — the plugin is calling get_plugin_data() before it is available, likely because the plugin is loading too early in the WordPress initialization sequence. The fix is clear from the WordPress debug mode output alone.

When reading the debug log, focus on the most recent entries first — the log appends new entries to the end, so errors from the current session are at the bottom of the file. Look for PHP Fatal error entries first, as these are the errors most likely to produce site-breaking symptoms. PHP Warning entries indicate non-fatal problems that may affect functionality. PHP Notice entries are informational and usually do not indicate problems that need immediate fixing. A well-maintained site running WordPress debug mode in a development environment should produce minimal warnings and no fatal errors.

Advanced WordPress Debug Mode Options

Beyond the three core constants, WordPress debug mode includes additional configuration options for specific diagnostic scenarios. These advanced options are useful for development environments and specific types of investigation.

The SCRIPT_DEBUG constant is useful alongside WordPress debug mode when investigating JavaScript errors or CSS problems. When set to true, WordPress loads the full unminified versions of its bundled scripts and stylesheets, which produce more readable error messages in the browser’s developer console and make it easier to identify which specific function or rule is causing a front-end problem. This constant should only be active in development environments — it significantly increases page load time and bandwidth usage.

Using WordPress Debug Mode on a Live Site — Safety Rules

Running WordPress debug mode on a live site requires strict adherence to the safety configuration described above. The most dangerous mistake is enabling WordPress debug mode with WP_DEBUG_DISPLAY set to true — this prints PHP error messages directly into the HTML of every page, making them visible to every visitor. PHP error messages expose file paths, database query structures, and code logic that can provide attackers with useful information about the site’s infrastructure. I have seen sites where a developer enabled WordPress debug mode with display on and forgot to disable it, leaving technical error output exposed to the public for weeks.

The safe WordPress debug mode pattern for live sites: enable debug mode with display off and logging on only for as long as it takes to diagnose the specific problem. Active WordPress debug mode with WP_DEBUG_LOG enabled generates log file entries for every PHP warning and notice across the entire site — on a busy site, this log can grow very large very quickly, consuming disk space. After collecting the error information needed for diagnosis, disable WordPress debug mode by returning WP_DEBUG to false and deleting the debug log file. The log file at wp-content/debug.log is also accessible via a direct web URL (yoursite.com/wp-content/debug.log) on servers where directory protection is not configured — adding a deny from all rule in a .htaccess file inside the wp-content/ directory prevents public access to the log.

For development environments and local WordPress installations where public exposure is not a concern, WordPress debug mode can run with WP_DEBUG_DISPLAY set to true continuously — seeing errors directly in the browser is faster for development work than repeatedly downloading and reading the log file. Development tools like Query Monitor provide even richer WordPress debug mode information directly in the WordPress admin bar, showing database query counts, hook execution times, and HTTP API call details that the standard debug log does not capture.

When to Disable WordPress Debug Mode

Knowing when to disable WordPress debug mode is as important as knowing how to enable it. The situation where WordPress debug mode should always be disabled: any publicly accessible production site where you are not actively investigating a specific problem. WordPress debug mode is a diagnostic tool, not a permanent configuration.

After using WordPress debug mode to diagnose and fix a problem, disable it by reversing the changes to wp-config.php: set WP_DEBUG back to false. The WP_DEBUG_LOG and WP_DEBUG_DISPLAY constants can be left in place set to their safe values, or removed entirely — either approach results in the same behaviour when WP_DEBUG is false. Delete the debug.log file from wp-content/ after you have finished reviewing it, since there is no reason to keep a file of old error messages on the server indefinitely.

Our guide on how to troubleshoot WordPress errors covers the full systematic diagnostic approach in which WordPress debug mode is one of the primary tools — reading the debug mode guide alongside the troubleshooting guide gives the complete picture of how to use error information effectively once WordPress debug mode has surfaced it. Our guide on fixing the WordPress white screen of death covers the scenario where WordPress debug mode is the difference between a blank page with no information and a PHP error message with a specific file path to investigate. The WordPress developer documentation on debugging covers every WordPress debug mode constant in technical detail, including the interaction between WP_DEBUG and WordPress’s fatal error recovery system introduced in WordPress 5.2. If this sounds familiar, How to Fix WordPress Stuck in Maintenance Mode Safely With Proven Steps is worth a look.