WordPress Debug Mode: How to Use WP_DEBUG and the Debug Log Safely
Debug mode makes WordPress report the errors it normally hides, which is how you find the plugin behind a white screen, a critical error or a broken page. Switched on carelessly, it also shows those errors to every visitor. Here are the lines to add, where the log goes, and how to keep it private.
In this article
Key takeaways
- Debug mode is three constants in wp-config.php: WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY.
- WP_DEBUG on its own shows errors on the page, because WP_DEBUG_DISPLAY defaults to true.
- On a live site, log instead: WP_DEBUG_LOG true and WP_DEBUG_DISPLAY false.
- The log goes to wp-content/debug.log, a public folder; point it outside the web root if you can.
- Read the last fatal error first: its file path names the plugin or theme behind it.
- Switch debug mode off when you're done; WordPress's handbook says it isn't meant for live sites.
The short answer
Log errors to a file, don’t show them on the page. In wp-config.php, set:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );- Change the existing
define( 'WP_DEBUG', false );line totrue, and add the other two lines below it, above/* That's all, stop editing! */. - Reload the page that’s broken.
- Read
wp-content/debug.log: the last fatal error names the file, and so the plugin or theme. - Fix it, then switch debug mode off and delete the log.
What each setting does
| Constant | Default | What it does |
|---|---|---|
WP_DEBUG | false (true on development environments) | Reports every error, warning and notice |
WP_DEBUG_LOG | false | true writes to wp-content/debug.log; a file path writes there |
WP_DEBUG_DISPLAY | true | Prints errors into the page; false hides them |
SCRIPT_DEBUG | false | Loads WordPress’s unminified CSS and JavaScript |
SAVEQUERIES | off | Saves every database query with how long it took |
Two details from WordPress 7.1’s own code matter most:
WP_DEBUG_DISPLAYdefaults to true. Turn onWP_DEBUGalone and every warning appears in the page, for every visitor. Set it to false on any site people can see.WP_DEBUG_LOGandWP_DEBUG_DISPLAYonly work withWP_DEBUGon. Without it, WordPress reports serious errors and warnings only, with no notices or deprecation messages.
Errors are never printed into AJAX, REST API or other JSON responses, so problems in the block editor or a form often only show up in the log.
1. Turn debug mode on
Open wp-config.php in the site’s root folder with your host’s file manager or SFTP. WordPress’s sample file already contains define( 'WP_DEBUG', false );: change that line to true rather than adding a second one, then add the log and display lines under it, above /* That's all, stop editing! */.
With WP-CLI you can do the same from the command line:
wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --rawThe --raw flag writes true and false as values rather than as quoted text. Working on a copy of the site? A staging sandbox is the right place to leave debug mode on for a while, which is what WordPress’s own debugging handbook recommends.
2. Reproduce the problem and read the log
Load the broken page again, or repeat the action that fails. Then open wp-content/debug.log and start at the bottom. A typical fatal error looks like this:
[13-Nov-2026 09:41:07 UTC] PHP Fatal error: Uncaught Error: Call to undefined function example_get_items()
in /var/www/html/wp-content/plugins/example-plugin/includes/items.php:42- The path names the culprit:
wp-content/plugins/example-plugin/points at that plugin,wp-content/themes/…at a theme. - Fatal errors first. Notices and deprecation messages are common in plugin code and often harmless; a fatal error stops the page.
- Match the time. The timestamp tells you whether a line belongs to the problem you just reproduced.
- Specific errors have their own fixes: “Allowed memory size … exhausted” is a memory limit problem, “Error establishing a database connection” a database connection problem, and a blank page or “There has been a critical error” is covered in our guides to the white screen of death and the critical error.
For a closer look, Query Monitor (200,000+ active installs, updated 27 October 2026, tested with WordPress 7.1.4) shows PHP errors, database queries, hooks and HTTP calls for each page you load as an administrator.
3. Keep the log private
wp-content is a public folder, so on most servers anyone who guesses the address can download debug.log, with file paths and sometimes data from your site in it. WordPress’s own Site Health check warns about exactly this: “Your site is set to log errors to a potentially public file”, and it marks the problem critical when the log sits inside the WordPress folder.
The fix is to give WP_DEBUG_LOG a path outside the public web folder instead of true. Your host’s file manager shows which folders sit above the site’s root:
define( 'WP_DEBUG_LOG', '/home/youraccount/logs/wp-errors.log' );If you can’t write outside the web root, keep the log on for as short a time as possible and delete debug.log when you’re done.
4. Switch it off again
- Set
WP_DEBUGback tofalseand remove the lines you added (or setWP_DEBUG_LOGback to false). - Delete
debug.log, or the log file at your own path. - Check Tools → Site Health: it should report “Your site is not set to output debug information”.
- Turn off
SCRIPT_DEBUGandSAVEQUERIEStoo if you used them; both slow the site down.
Plugins that help
You don’t need a plugin to debug WordPress, but these save time. Figures from WordPress.org on 13 November 2026:
| Plugin | Active installs | What it does |
|---|---|---|
| Query Monitor | 200,000+ | A developer panel for each page: PHP errors, database queries grouped by plugin, hooks, scripts and HTTP calls. Tested with 7.1.4 |
| Error Log Monitor | 20,000+ | A dashboard widget with the latest lines of your PHP error log, visible to administrators only, and optional email alerts. Tested with 7.1.4 |
| Debug Bar | 20,000+ | A debug menu in the admin bar with queries, cache and, with WP_DEBUG on, warnings and notices. Tested with 7.0.8 |
| WP Debugging | 10,000+ | Writes the debug constants into wp-config.php when you activate it and removes them when you deactivate it. It also turns PHP’s display_errors on while active, so use it on a staging copy. Tested with 7.1.4 |
When the log stays empty
- The error happens before WordPress loads, for example a typo in
wp-config.phpitself. Only your host’s PHP error log will show it. - Check the constants are read: a second
define( 'WP_DEBUG', … )further up wins, and lines added at the very end of the file, afterwp-settings.phpis loaded, come too late. - The fatal error handler is catching it. On a live site WordPress shows its critical error page and emails the admin a recovery link; the error itself is still logged. Showing fatal errors on screen also needs
WP_DISABLE_FATAL_ERROR_HANDLER, which is for development copies only.
Back up the site before you start changing plugins or themes; our guide to backing up WordPress covers it.
Where WPOS fits
WPOS can’t edit wp-config.php for you; your host’s file manager or SFTP does that. Once logging is on, the agent can read the log, tell you which plugin or theme threw the error, and try the fix on a staging sandbox before it touches the live site. It checks its own work with a browser screenshot before it reports a change as done:
“Read the last 50 lines of the debug log, tell me which plugin caused today’s fatal errors, and test switching it off on the staging sandbox.”
WPOS is our product, so weigh this section accordingly; you can try it free for 30 days with 5,000 credits, a live site plus a staging sandbox, and no card.
Frequently Asked Questions
In wp-config.php, change define( 'WP_DEBUG', false ); to true and add define( 'WP_DEBUG_LOG', true ); and define( 'WP_DEBUG_DISPLAY', false ); above the line "That's all, stop editing!". Errors then go to wp-content/debug.log instead of the page. With WP-CLI: wp config set WP_DEBUG true –raw.
In wp-content/debug.log by default, once WP_DEBUG and WP_DEBUG_LOG are both true. Set WP_DEBUG_LOG to a full file path instead of true to write it somewhere else, ideally outside the public web folder.
Not on a live site. WordPress's handbook says the debug tools are meant for local testing and staging, and Site Health flags a site that shows errors to visitors or logs them to a public file. Turn it off once you've found the problem.
Check the lines sit above "That's all, stop editing!" and that WP_DEBUG isn't defined twice: wp-config.php already contains it, so change that line rather than adding a second. With WP_DEBUG_DISPLAY false, errors only go to the log, and errors during AJAX and REST requests never show on the page.
It makes WordPress load the full, unminified versions of its own CSS and JavaScript, which helps when you're tracking down a script error in the editor or wp-admin. Turn it off again afterwards.
WP_DEBUG makes WordPress report every notice and warning and lets it write its own debug.log. Your host's PHP error log records errors too, including ones that happen before WordPress loads, such as a typo in wp-config.php, so check it when debug.log stays empty.
Start free with 15,000 credits.
Three times the usual 5,000, no card needed. Then 50% off your site licences for 2 months with FRIDAY50.
Find the error, not just the symptom.
WPOS puts an AI agent inside wp-admin on the sites you already run, on any host, and it checks its own work. Free for 30 days: 5,000 credits, a live site plus a sandbox, no card.