WordPress Debug Mode: How to Enable It, Read debug.log and Turn It Off Safely

A plugin update finishes, you refresh the page, and instead of your site you get a blank white screen or the message “There has been a critical error on this website.” WordPress knows exactly what went wrong. It just is not telling you yet. Debug mode is how you make it talk.

This guide covers three ways to enable WordPress debug mode (a plugin, wp-config.php and WP-CLI), where the debug.log file is saved, how to read an error line so you know which plugin or theme to blame, and how to turn debug mode off again without leaving error messages or a public log file behind. Every code snippet uses straight quotes, so you can paste it into wp-config.php as it is.

Quick answer: to enable WordPress debug mode, open wp-config.php in your site’s root folder and replace the line define( 'WP_DEBUG', false ); with the code below. If your file has no WP_DEBUG line, paste the code just above the line that says “That’s all, stop editing!”. Errors are saved to wp-content/debug.log and hidden from visitors. Set WP_DEBUG back to false when you are done.

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Last reviewed in September 2026 against the WordPress core source code, the official Debugging in WordPress handbook and WP Debugging 2.12.6.

What Is WordPress Debug Mode?

WordPress debug mode is a setting controlled by the WP_DEBUG constant in wp-config.php. It is off by default. When you set it to true, WordPress reports every PHP error, warning and notice produced by core, your theme and your plugins, plus notices about deprecated functions that are due to be removed. Two companion constants decide where those messages go: WP_DEBUG_LOG writes them to a file, and WP_DEBUG_DISPLAY controls whether they are printed on the page.

Every debugging constant is documented in the official Debugging in WordPress handbook, which is worth bookmarking because it is updated alongside WordPress releases. Here is what each one does in practice:

Constant	What it does	Default	When to use it
WP_DEBUG	Turns debug mode on or off	false	Any time you are troubleshooting
WP_DEBUG_LOG	Saves messages to debug.log in the content folder (usually wp-content), or to a file path you choose	false	Almost always, together with WP_DEBUG
WP_DEBUG_DISPLAY	Prints messages inside the page HTML	true	Set it to false on any site a visitor can reach
SCRIPT_DEBUG	Loads the unminified versions of core CSS and JavaScript	false	When you are tracking down a core script or block editor issue
SAVEQUERIES	Stores every database query so you can inspect it	false	Short sessions on staging only, because it slows the site

WP_DEBUG_LOG and WP_DEBUG_DISPLAY do nothing unless WP_DEBUG is true.

Debug mode has limits, too. It does not catch JavaScript errors, which appear in your browser console instead (press F12). It also cannot log a syntax error inside wp-config.php itself, because that happens before WordPress loads. Those errors go to your server’s PHP error log, which most hosting panels let you view.

One thing that catches people out after a PHP upgrade: PHP 8 promoted several common notices, such as reading an undefined variable or array key, to warnings. A plugin that produced a few quiet notices on PHP 7.4 can fill debug.log with warnings on PHP 8 without a single line of its code changing.

Before You Enable Debug Mode

Debugging means editing the file that holds your database credentials, so a minute of preparation pays for itself.

• Use a staging copy if you can. A WordPress staging environment lets you show errors on screen, switch themes and deactivate plugins without a single visitor seeing it.
• Take a full backup. Make a complete backup of your website, files and database, before you touch wp-config.php.
• Keep an untouched copy of wp-config.php. Download it to your computer first. If an edit goes wrong, uploading that copy restores the site in seconds.
• Edit in a code editor. Use VS Code, Sublime Text or Notepad++. Word processors and many note apps turn straight quotes into curly ones, and one curly quote in wp-config.php is enough to cause a fatal error.

Which Debug Settings Do You Need?

The right combination depends on where the site lives and who can see it.

Situation	WP_DEBUG	WP_DEBUG_LOG	WP_DEBUG_DISPLAY
Local or staging site	true	true	true, so you see errors as you work
Live site, bug only happens in production	true	true, ideally a private file path	false
Critical error or white screen of death, no wp-admin access	true	true	false
Normal day-to-day live site	false	not needed	not needed

For both live-site rows, the goal is log-only mode: errors are written to a file you can read, and visitors never see file paths or plugin names on the page. Use Method 2 or Method 3 for that, and switch it off as soon as you have what you need.

Prefer to watch first? This walkthrough from our YouTube channel shows how to enable and disable debug mode step by step:

Method 1: Enable Debug Mode With the WP Debugging Plugin

If you are working on a staging copy, can still log in to wp-admin and would rather not edit files, the free WP Debugging plugin by Andy Fragen writes the debug constants into wp-config.php for you and removes them when you deactivate it. It needs a writable wp-config.php, so if your host locks that file, skip to Method 2.

1. Go to Plugins > Add New Plugin.
2. Type WP Debugging in the search field.

3. Click Install Now on WP Debugging, then click Activate.
4. Go to Tools > WP Debugging. On a Multisite network, it is under Network Admin > Settings > WP Debugging.
5. Make sure Set WP_DEBUG to true is checked.
6. Click Save Changes.

Why WP Debugging Belongs on Staging, Not a Live Site

The settings page offers a “Set WP_DEBUG_DISPLAY to false” option, and it is natural to assume that ticking it hides errors from visitors. It does not fully do that. The plugin’s own code (version 2.12.6) switches PHP’s display_errors setting on for every request while the plugin is active, and it does so after WordPress has already applied your WP_DEBUG_DISPLAY choice. In practice, most warnings and notices can still print on the page.

The plugin also turns on SCRIPT_DEBUG and SAVEQUERIES by default, and SAVEQUERIES adds overhead to every page load. So use it on a staging site, activate it for a debugging session and deactivate it afterwards. Deactivating removes the constants it added and restores whatever was there before. For log-only debugging on a live site, use Method 2 or Method 3 instead.

Method 2: Enable Debug Mode Manually in wp-config.php

Use this method on a live site, when you cannot log in (after a critical error, for example), when your host blocks plugins from writing to wp-config.php, or when you simply want full control over the settings.

Step 1: Open wp-config.php

wp-config.php sits in your WordPress root folder, usually public_html or www, next to the wp-admin and wp-content folders. Some hardened setups move it one level above the root. You can open it in three ways:

• Your host’s File Manager. cPanel, Plesk and most custom hosting panels have one. Right-click the file and choose Edit.
• An SFTP or FTP client such as FileZilla. Connect with the credentials from your hosting panel, open the root folder, download wp-config.php, edit it on your computer, then upload it back and overwrite the original.
• SSH. If your host provides it, Method 3 below is faster than editing by hand.

Step 2: Find the Existing WP_DEBUG Line

Scroll toward the bottom of the file. Most installs already contain this line, a few lines above the comment that starts with “That’s all, stop editing!”:

define( 'WP_DEBUG', false );

Replace that line instead of adding a new one below it. This is the most common reason debug mode “doesn’t work.” If the original false line stays in the file and you add a true line further down, PHP keeps the first value it sees, WP_DEBUG stays false, and PHP raises a “Constant WP_DEBUG already defined” warning you will probably never see.

Step 3: Paste the Debug Code

Replace the line with this block. It turns on debug mode, saves every message to wp-content/debug.log, and keeps messages off the page:

// Turn on WordPress debug mode
define( 'WP_DEBUG', true );

// Save errors, warnings and notices to wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Keep messages off the screen so visitors never see them
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

On a local or staging site where nobody else is looking, you can set WP_DEBUG_DISPLAY to true and remove the ini_set line to see each error printed right where it happens. Whatever you use, it must stay above the “That’s all, stop editing!” comment. Anything placed below the require_once line that loads wp-settings.php is read too late to have any effect.

Step 4: Save, Upload and Reproduce the Problem

Save the file, and upload it if you edited a local copy. Then do whatever triggered the problem: load the broken page, submit the form, run the import. WordPress creates debug.log only when it has something to write, so the file appears after the first error, not the moment you save.

To confirm debug mode is really on without opening the file again, go to Tools > Site Health > Info and expand WordPress Constants. WP_DEBUG should read Enabled, and WP_DEBUG_LOG should read Enabled or show your custom file path.

Method 3: Enable Debug Mode With WP-CLI

If your host gives you SSH access, WP-CLI edits wp-config.php for you, which rules out curly quotes and duplicate constants. Run these commands from the WordPress root folder:

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

The --raw flag writes true and false as real booleans. Without it, WP-CLI wraps the value in quotes, and a quoted 'false' actually switches debug mode on (the FAQ below explains why). To turn debugging off later, run wp config set WP_DEBUG false --raw.

Some managed WordPress hosts also add a debug switch to their own dashboard. WordPress itself has no such toggle in wp-admin, so if you do not see one in your hosting panel, use one of the three methods above.

Where Is the WordPress Debug Log?

By default, WordPress saves the debug log as debug.log inside the content folder, which is wp-content on almost every site. You can open it in any of these ways:

• File Manager or FTP: open the wp-content folder, then open or download debug.log.
• The WP Debugging plugin: it bundles Debug Quick Look, which adds a Debug Quick Look menu to the admin bar. Choose View File to read the log in a new tab, or Purge File to empty it.
• SSH: tail -n 50 wp-content/debug.log shows the 50 most recent lines. New entries are added at the end of the file, so always read from the bottom up.

If you want to go further, such as writing your own variables to the log with a small helper function or reading it through a log viewer plugin, our guide on how to use the WordPress debug log walks through that workflow.

Keep debug.log Private

On many servers, anyone who types yoursite.com/wp-content/debug.log into a browser can read your log. That file lists server paths, plugin names and sometimes database details, which is exactly the map an attacker is looking for. WordPress warns about this itself: while logging is on, Site Health shows “Your site is set to log errors to a potentially public file” and marks it critical when the log sits inside your WordPress folder. There are two fixes, and you can use both.

Move the log outside the public folder by giving WP_DEBUG_LOG a full file path instead of true. The folder must already exist and be writable by PHP:

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

Or block direct access to the file. On Apache 2.4, add this to the .htaccess file in your WordPress root:

<Files "debug.log">
    Require all denied
</Files>

On Nginx, ask your host to deny access to .log files, or add location = /wp-content/debug.log { deny all; } to your server block if you manage the server yourself.

How to Read a debug.log Entry

A debug log looks like noise until you notice that every line follows the same pattern. Here is an example entry. The plugin name is made up, but the format is exactly what WordPress writes:

[29-Sep-2026 14:02:11 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function wc_get_product() in /home/example/public_html/wp-content/plugins/example-addon/includes/cart.php:118

• [29-Sep-2026 14:02:11 UTC] is when it happened, always in UTC. Match it to the moment you reproduced the problem.
• PHP Fatal error is the severity. Fatal errors stop PHP and cause the critical error screen. Warnings mean something failed but the page kept loading. Notices are minor coding issues. Deprecated messages flag code that WordPress or PHP plans to remove, so fix those before your next major update.
• Call to undefined function wc_get_product() is what went wrong. In this example, an add-on is calling a WooCommerce function while WooCommerce is deactivated.
• /wp-content/plugins/example-addon/ is the most useful part. The folder name after /plugins/ or /themes/ tells you which plugin or theme to investigate, and often that is the whole answer.
• cart.php:118 is the exact file and line number, which is what the plugin developer will ask for when you open a support ticket.

These are the messages you will run into most often, and where to start with each one:

Message in debug.log	Usual cause	First fix
Allowed memory size of … bytes exhausted	PHP ran out of memory	Raise the limit. Our guide to fixing the PHP memory limit in WordPress covers wp-config.php, php.ini and .htaccess.
Call to undefined function	A plugin depends on another plugin that is inactive, or needs a newer PHP version	Reactivate the dependency or check the plugin’s PHP requirement
Cannot redeclare	The same function is defined twice, often a snippet pasted into functions.php that also exists in a plugin	Remove the duplicate
Cannot modify header information, headers already sent	Blank space or text before <?php or after a closing ?> tag, usually in functions.php or wp-config.php	Delete the stray characters
Maximum execution time of 30 seconds exceeded	A long import, backup or loop	Raise max_execution_time or split the task into smaller batches
WordPress database error	A database query failed	Check the table named in the message, then repair it or restore it from backup

Why this matters in practice: when a layout breaks after an update, the theme usually gets the blame, because the theme is what visitors see. The path in the fatal error often tells a different story and points to a plugin folder instead. Reading the last 20 or 30 lines of debug.log before you deactivate anything turns a vague “my site is broken” into a one-line answer.

debug.log Not Created? Check These 7 Things

1. WP_DEBUG is defined twice. The original false line is still in the file above your new true line. Delete one of them.
2. The code is in the wrong place. It has to sit above the “That’s all, stop editing!” comment, not below the line that loads wp-settings.php.
3. No error has happened yet. The file is created only when there is something to log. Reproduce the problem.
4. You are looking at a cached page. If a page cache serves a stored copy, the PHP that throws the error never runs. Clear the cache, or test while logged in.
5. PHP cannot write to the folder. The PHP user needs permission to create files in wp-content, or in the custom folder you set. A custom path to a folder that does not exist fails silently.
6. The error happens before WordPress loads. A syntax error in wp-config.php or a server configuration problem goes to the server’s PHP error log, not to debug.log.
7. Your host overrides error logging. Some managed hosts route PHP errors to their own log viewer, and a must-use plugin can replace the error handler. Check your host’s documentation or ask support where PHP errors are written.

How to Disable WordPress Debug Mode

Once you have found the problem, turn off debug mode. Leaving it on means a log file that keeps growing and, if display is on, error messages that show visitors your file paths.

Open wp-config.php and set WP_DEBUG back to false. You can delete the WP_DEBUG_LOG and WP_DEBUG_DISPLAY lines or leave them in place, because they do nothing while WP_DEBUG is off:

define( 'WP_DEBUG', false );

Then finish the cleanup:

• If you used the WP Debugging plugin, deactivate it. That removes the constants it added.
• Delete wp-content/debug.log, or your custom log file. WordPress never trims it, so on a busy site it can reach gigabytes, and an old log is still readable by anyone who finds the URL. Download a copy first if a developer needs it.
• Clear your page cache and CDN cache so no stored page still carries error output.
• Check Tools > Site Health > Info > WordPress Constants. WP_DEBUG should now read Disabled.

Hide PHP Warnings on a Live Site

Some hosts switch PHP’s display_errors on at server level, so warnings keep appearing in your header or footer even with WP_DEBUG set to false. To turn off PHP errors on the front end in that case, use this block. The ini_set line is the one that overrides the server setting:

define( 'WP_DEBUG', false );
@ini_set( 'display_errors', 0 );

If warnings still show, check whether the WP Debugging plugin is still active, because it switches error display back on. If it is not, the setting is locked in your server’s php.ini, and your host needs to set display_errors = Off. Keep in mind that hiding a warning does not fix it. The plugin or theme is still producing it, so report the message to its developer.

Other Ways to Debug WordPress

• Recovery mode. Since WordPress 5.2, a fatal error shows the critical error screen, and WordPress emails the site admin a special login link. That link opens wp-admin with the broken plugin or theme paused, so you can deactivate it without FTP. Check the admin inbox and the spam folder first. Developers who would rather see the raw fatal error on a staging site can add define( 'WP_DISABLE_FATAL_ERROR_HANDLER', true );, but never on a live site.
• Troubleshooting Mode. The free Health Check & Troubleshooting plugin can disable all plugins and switch to a default theme for your own logged-in session only, while visitors keep seeing the normal site. It is the safest way to test a suspected conflict on a live site.
• Query Monitor. This free plugin shows PHP errors, database queries, hooks and HTTP requests for the page you are viewing, and it attributes each query to the plugin that ran it. Our guide to WordPress plugin performance optimization shows how to use it to find the plugin that is slowing a page down.
• WooCommerce logs. Payment gateways and other WooCommerce extensions write their own logs under WooCommerce > Status > Logs, separate from debug.log. Check both when a checkout fails.
• Browser developer tools. JavaScript errors, blocked scripts and failed REST API calls show up in the Console and Network tabs, never in debug.log.
• Your server’s PHP error log. Useful for errors that happen before WordPress loads.
• Xdebug. For developers who need to pause code and inspect variables line by line in their editor on a local setup.
• Application monitoring such as New Relic. A paid option for production sites that need ongoing error and performance tracking rather than a one-off debugging session.

The Debugging Routine That Saves the Most Time

Turn on logging with display off. Reproduce the problem once. Read the newest fatal error at the bottom of debug.log and follow its path to the plugin or theme folder it names. Deactivate that one component and confirm the site is back. Then set WP_DEBUG to false and delete the log. It is faster, and far less disruptive for your visitors, than deactivating every plugin one by one and hoping the problem disappears.

If the log points to two plugins clashing rather than one broken plugin, our guide on how to fix WordPress plugin conflicts walks through the next steps.

WP_DEBUG Questions: Live Sites, Speed, Multisite and debug.log Cleanup