WordPress Debug Mode: How to Enable WP_DEBUG Safely

WordPress debug mode is a setting in wp-config.php that makes WordPress report every PHP error, warning and notice. You turn it on with define( 'WP_DEBUG', true ); placed above the “That’s all, stop editing!” line, and turn it off by changing true to false. On a live site, pair it with WP_DEBUG_LOG set to true and WP_DEBUG_DISPLAY set to false. Errors then go to a log file instead of showing up on the page for every visitor.

Key takeaways

• WP_DEBUG is the master switch. WP_DEBUG_LOG and WP_DEBUG_DISPLAY do nothing while it is false.
• On a live site, log errors to a file and keep display off, then switch debug mode off when you are done.
• Write true and false without quotes, and edit the existing WP_DEBUG line instead of adding a second one.

If you just want the right block of code for your site, the free WP_DEBUG code generator builds it in your browser, with display already switched off.

What debug mode changes

With WP_DEBUG off, WordPress only reports errors and warnings, and whether you ever see them depends on your host. Notices and deprecation messages are not reported at all. Setting WP_DEBUG to true turns on full error reporting (E_ALL), so those are reported too. WordPress also starts flagging deprecated functions and arguments, often naming the replacement you should use instead (Debugging in WordPress, developer.wordpress.org).

That is useful when something is broken and you have no idea why. The problem is where those messages go: by default they are printed straight into the HTML. That is fine on your laptop and a bad idea on a site people visit.

The debug constants, one by one

All of these live in wp-config.php, in your site’s root folder. They are read early in WordPress’s startup, so they only work when defined above the comment /* That's all, stop editing! Happy publishing. */ (older installs say “Happy blogging”). The official wp-config.php reference lists every setting the file accepts.

Constant	Default	What it controls
WP_DEBUG	false	The master switch. Reports notices, warnings and deprecations.
WP_DEBUG_LOG	false	Writes errors to a file. true means wp-content/debug.log; a file path sends them there instead.
WP_DEBUG_DISPLAY	true	Prints errors into the page HTML.
SCRIPT_DEBUG	false	Loads the unminified “dev” versions of core CSS and JavaScript.
SAVEQUERIES	not defined	Records every database query with its run time and the function that called it.

WP_DEBUG

This is the only one that turns debug mode on. WP_DEBUG_LOG and WP_DEBUG_DISPLAY are read inside the WP_DEBUG branch of WordPress’s startup code (the wp_debug_mode() function in wp-includes/load.php). With WP_DEBUG set to false, setting the other two does nothing. The official docs say it plainly: for WP_DEBUG_LOG to do anything, WP_DEBUG must be true.

WP_DEBUG_LOG

Set to true, it saves errors to debug.log inside your content folder, normally wp-content/debug.log. It catches errors you would never see on screen, such as ones thrown during AJAX requests or scheduled (cron) tasks.

You can also give it a file path instead of true, a feature added in WordPress 5.1:

define( 'WP_DEBUG_LOG', '/home/youruser/logs/wp-errors.log' );

The folder must already exist and PHP must be allowed to write to it. Our guide on the WordPress debug log location covers where the file ends up, why the default spot can be downloaded by anyone, and how to protect it.

WP_DEBUG_DISPLAY

This one defaults to true. If you only switch on WP_DEBUG, errors are echoed into your pages, including your server’s full file paths. Set it to false to keep them out of the HTML.

You can also set it to null. In that case WordPress leaves PHP’s own display_errors setting alone and uses whatever your host configured. false actively forces display off, which is what you want on a public site.

SCRIPT_DEBUG and SAVEQUERIES

These two are not part of debug mode proper, but they show up in the same block of wp-config.php.

SCRIPT_DEBUG makes WordPress load the readable, unminified versions of its core CSS and JavaScript. You need it when you are editing or tracing a problem inside core scripts, for example a block editor error in the browser console that points at a minified file.

SAVEQUERIES stores every database query in the global $wpdb->queries array, along with how long it took and which function ran it. It helps find slow queries, and WordPress warns that it has a performance cost, so leave it off unless you are measuring.

define( 'SCRIPT_DEBUG', true );
define( 'SAVEQUERIES', true );

How to enable WP_DEBUG safely on a live site

WordPress recommends against running debug tools on a live site; they are meant for local and staging copies. Some bugs only appear in production, with real traffic and real plugins. If that is your situation, this is the setup that keeps errors away from visitors:

1. Back up wp-config.php. Download a copy over SFTP or your host’s file manager before you touch it. One typo in this file can take down the whole site, including wp-admin.
2. Search for an existing WP_DEBUG line. Most installs already have define( 'WP_DEBUG', false );. Edit that line rather than adding a new one.
3. Set the three constants together, above the “stop editing” line:

// Turn on WordPress debug mode, log to a file, show nothing to visitors.
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

4. Reproduce the problem. Load the broken page or repeat the action that fails.
5. Read wp-content/debug.log. The newest entries are at the bottom.
6. Turn debug mode off as soon as you have what you need (next section).

The @ini_set( 'display_errors', 0 ); line comes from the example on WordPress’s own debugging page. It switches PHP’s own display_errors setting off immediately, before WordPress starts loading. Errors raised in those first moments stay hidden too.

If your host has WP-CLI, you can set the same values without opening the file. The --raw flag of wp config set writes a real boolean instead of the text "true":

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

Want this block generated for you, with an optional private log path? The WordPress debug log generator gives you a ready-to-paste version.

How to turn off debug mode

Change the master switch back:

define( 'WP_DEBUG', false );

That alone stops logging and display, because the other two constants are ignored once WP_DEBUG is false. You can leave the WP_DEBUG_LOG and WP_DEBUG_DISPLAY lines in place for next time, or delete them.

Then deal with the log. Switching debug mode off does not delete debug.log; the file stays on the server with everything it collected, and in the default location it can often be opened in a browser. Download it if you want to keep it, then delete it.

Common mistakes

Putting the code below “That’s all, stop editing!” WordPress loads its settings right after that comment. A constant defined further down arrives too late to change anything. This is the usual reason people say “I set WP_DEBUG to true and nothing happened.”

Defining WP_DEBUG twice. Say the file already contains define( 'WP_DEBUG', false ); and you paste a new true line under it. PHP keeps the first value and complains that the constant is already defined (a warning on PHP 8, a notice on older versions). Debug mode stays off and you get an extra warning. Edit the existing line instead.

Quoting true or false. define( 'WP_DEBUG', 'false' ); turns debug mode on. A quoted word is a string, and PHP reads any non-empty string as true. The WordPress docs call this out. Write true and false with no quotes.

Turning on WP_DEBUG alone. Because WP_DEBUG_DISPLAY defaults to true, a lone define( 'WP_DEBUG', true ); prints errors and file paths on your public pages. Messages printed early can also break redirects, because WordPress can no longer send its redirect headers.

Forgetting to switch it off. Nothing in WordPress core trims debug.log. A plugin that throws a notice on every page load can grow the file until the disk is full. Set a reminder when you turn debug mode on.

Editing the file in a word processor. Smart quotes (' turned into curly quotes) break PHP. Use a plain text editor or your host’s code editor.

Where debug mode fits when your site is broken

Debug mode is the first step for most WordPress errors because it turns a vague symptom into a file name and line number. Seeing “There has been a critical error on this website”? The WordPress critical error guide explains that message and how to disable the plugin behind it. For a blank page, the white screen of death guide uses the same logging setup. If the log shows “Allowed memory size exhausted”, head to the memory exhausted fix.

Debug mode on but the log stays empty? First confirm that WP_DEBUG really is true, with no quotes and no duplicate line. Then check that PHP can write to wp-content. Last, ask whether your host sends PHP errors to its own log viewer instead.

Ready to set it up? Generate your wp-config.php debug block with the free WordPress debug log tool, paste it above the “stop editing” line, and remember to set WP_DEBUG back to false when you are done.