WordPress Debug Mode: Turn On WP_DEBUG Safely

Sooner or later, someone helping with a broken WordPress site says “turn on debug mode and tell me what it says”. It sounds simple, and it mostly is: a couple of lines in one file. But done carelessly it can print file paths and error details to every visitor, fill your disk with a log nobody reads, or leave a file of sensitive information sitting where anyone can download it.

This post is about doing it properly. How to switch debugging on so that errors go to a private log instead of the screen, what the different settings do, what the output means when it starts arriving, and how to switch it off again. If you already have a log and want help making sense of it, our companion piece on finding and reading WordPress error logs picks up where this one stops.

What debug mode is, and what it is not

WordPress, its plugins and its theme are written in PHP. When PHP runs into something wrong, it raises a message: a deprecation notice, a warning, or a fatal error that stops the page. On a normal live site, WordPress hides most of these. That is correct for visitors, but it means that when something breaks, you see a blank page or the generic “There has been a critical error on this website” and nothing that tells you why.

Debug mode tells WordPress to stop hiding them. It does not fix anything and it does not make the site slower in any meaningful way on its own. It simply makes the reason visible, to you, in the place you choose.

Before you edit wp-config.php

All of the settings below live in wp-config.php, in the main WordPress folder. This file also holds your database password, and a single missing semicolon in it will take the whole site down. So two precautions, briefly:

• Download a copy of the file to your computer before changing it, so you can put the original back in seconds.
• Edit it with a plain text editor or your host’s file manager editor, never a word processor, which can add invisible characters.

If you have a staging copy of the site, it is the better place to reproduce the problem, though many errors only show on the live site, and the settings below are safe to use there.

The safe setup: log errors, do not display them

Open wp-config.php and look for a line that already mentions WP_DEBUG. Most installations have one, set to false:

define( 'WP_DEBUG', false );

Change that line rather than adding a second copy. Defining the same constant twice causes a warning of its own, which is an unhelpful way to start. Replace it with these lines, keeping them above the comment that says That’s all, stop editing!:

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

Here is what each line does:

• WP_DEBUG switches debugging on. On its own, with nothing else, it also prints errors on screen, which is why the other lines matter.
• WP_DEBUG_LOG writes every message to a file. Set to true, the file is wp-content/debug.log. You can instead give it a full path in quotes, which lets you put the log outside the public web folder.
• WP_DEBUG_DISPLAY set to false stops WordPress showing messages in pages.
• The display_errors line asks PHP itself not to show them either, in case the server is set to display errors regardless.

Save the file, upload it if you edited a local copy, and reload the page that was failing. If anything goes wrong, the log file appears in wp-content.

Keep the log private

The default debug.log sits in a public folder. On many servers anyone who guesses its address can open it in a browser, and it can contain file paths, plugin names and sometimes snippets of data. Three ways to deal with that:

1. Point the log elsewhere. Give WP_DEBUG_LOG a path outside the web root, for example a folder alongside your public_html or httpdocs rather than inside it. Your host’s file manager will show you the full path.
2. Block access to it with a server rule, which your host or developer can add.
3. Keep the time short. Turn debugging on, reproduce the problem, read the log, then turn it off and delete the file.

The same thinking applies to wp-config.php itself; our article on protecting wp-config.php covers that file.

Two more settings you may be asked about

SCRIPT_DEBUG

define( 'SCRIPT_DEBUG', true ); makes WordPress load the full, unminified versions of its own JavaScript and CSS files. It is useful when a developer is tracking down a problem in the editor or dashboard scripts. It does not affect PHP errors and has no place on a live site once the investigation is over.

SAVEQUERIES

define( 'SAVEQUERIES', true ); records every database query along with how long it took and which function ran it. It helps with slow pages, usually together with a tool such as the Query Monitor plugin, but it uses extra memory on every request. Switch it on only briefly.

What the messages mean

Once logging is on, you will see lines tagged with one of a few labels. They are not equally serious.

A busy log full of deprecation notices on an older site is common and does not mean the site is falling apart. Look for the fatal errors first, then the warnings that mention the plugin or page you are investigating.

Debug mode and the recovery mode email

Since WordPress gained its fatal error protection, a site that hits a fatal error usually shows “There has been a critical error on this website” and emails the site administrator a special login link. That link opens the dashboard in recovery mode with the faulty plugin or theme paused. The email also names the file and line that failed, which is often all you need without touching debug settings at all.

If the email never arrives, debug mode is the next best route to the same information. And if you see developers mention WP_DISABLE_FATAL_ERROR_HANDLER, that switches the protection off, which is occasionally useful while debugging but should not be left on a live site.

What to do with what you find

• The error names a plugin folder. Note the plugin, and check whether an update is available or whether it was just updated. Deactivating it, or renaming its folder if you cannot reach the dashboard, usually brings the site back.
• The error names your theme. Check whether someone edited theme files recently. Switching to a default theme briefly tells you whether the theme is at fault.
• The error mentions memory. Something used more memory than PHP allows. Our post on the memory exhausted error explains the limits involved.
• The error names a core file in wp-includes. Core is rarely the real cause. Read the lines just above for the plugin that called it.
• The log is empty but the site still fails. The problem may be at the server level, before WordPress even loads. A 500 error with nothing in debug.log usually means looking in the server’s own error log instead, as we describe in our page on fixing 500 errors.

Switching it off again

When you are done, set WP_DEBUG back to false and remove or comment out the other lines you added. Delete debug.log, or move it somewhere private if you need to keep it for a developer. A log left running on a live site keeps growing, and on a small hosting plan it can eat into the storage you need for backups and email.

Leaving debug mode on permanently with display switched off is not a disaster, but there is little reason for it on a stable site. Turn it on when there is something to investigate.

Where this fits

Debug mode is the first tool for nearly every error in our WordPress error guide, because it turns a vague symptom into a specific file and line number. That alone often makes the difference between hours of guessing and a quick repair.

When the message makes no sense

If you have the log but the lines mean nothing to you, that is normal; they are written for developers. Copy the fatal error line and send it to us on WhatsApp along with what you were doing when the site broke. We will tell you plainly what it points to and, if you want us to, fix it with a backup taken first. When the site is showing a critical error right now, our critical error repair is the place to start.

Next in this series: How to Find and Read a WordPress Error Log